External Webhook Integration Architecture - commercetools Connector
Essential knowledge
Intended Audience:
Technical User
Author:
Fluent Commerce
Changed on:
30 June 2026
Overview
Explains how the commercetools Connector ingests inbound webhooks and dispatches outbound payloads across the integration ecosystem. Partners will learn to configure and apply this shared framework utility, which manages message routing, handler resolution, and internal queue mechanics. For the business, this asynchronous architecture ensures real-time, secure data transmission and protects platform stability by preventing message loss during high-volume storefront traffic spikes.Note: This architectural component serves as a global framework utility rather than a single functional pipeline.Key points
- Core Function & Outcome: You will learn how the framework utility orchestrates bidirectional ingress and egress loops, serving as the master execution blueprint for all entity-specific data synchronization pipelines.
- Asynchronous Queue Infrastructure: The architecture processes incoming webhook payloads through an external
`ct-queue`and an internal Event Queue sequentially, decoupling network reception tasks from backend data processing to maintain platform throughput. - Declarative Route Filtering: Implementing partners can manage message names, configure explicit inclusion filters, and reassign target event pathways directly inside the
`application-connector.yml`configuration file. - Extensible Handler Architecture: The core message routing and processing layers are completely decoupled, allowing developers to cleanly register custom storefront event handlers by extending the base
`MessageHandler`class.
Data Pipeline Execution
1. Ingestion (Webhook/Batch Job)
- CT Queue: Webhook notifications are pushed to the
`ct-queue`. - CT Queue Listener: This class reads the message from the
`ct-queue`and pushes it to the Event Queue. - Event Queue: This queue is responsible for holding the event message until it is processed.
2. Processing & Payload Extraction
- Message Router: The router reads the message name from the Event Queue and passes it to the corresponding handler.
- Message Handling: The handler reads the message data, fetches additional information via the SDK, maps it to the Fluent data model, and pushes the resulting data to the Fluent OMS.
3. Execution & Customization
- Extensibility: Handlers are fully extensible, allowing partners to modify the logic as required for their specific implementation.
- Route Configuration: Partners can manage message names and override handler classes via the
`application-connector.yml`.
Data Storage & Schema Mapping
The following mapping framework is applied to webhook payload routing:| Component | Description |
| CT-Queue | Entry point for incoming webhook events. |
| Message Router | Maps message names to specific handlers. |
| Fluent OMS | Destination for transformed/mapped data. |
Developer Extension Points
Implementation Patterns
- Overriding Handlers: Partners can override existing handlers by updating the
`application-connector.yml`file to point to a new handler class. - New Handlers: New handlers can be added by extending the
`MessageHandler`class and ensuring the package is within`com.fluentcommerce.connect`.
