Custom Integrations

💼 Business Context

• Not every destination fits a standard shape — a niche partner system, an unusual delivery cadence, a proprietary protocol — and this pattern exists so those cases don't get hacked into an ill-fitting standard connector
• Keeps one-off integrations maintainable by building them on the same shared conventions as every standard destination
• Owned by Platform Engineering, individual connectors owned by the requesting team

🔌 Technical Overview

A custom connector is a .NET Core service scaffolded from a shared template (mirroring the Ingestion Layer's Connectors pattern in reverse), packaged as its own Docker container on Azure Container Apps, and registered with the Activation API's dispatch layer so it can subscribe to the same Azure Service Bus events as any standard destination. It follows the same observability conventions (Application Insights tracing, Azure Monitor alerting) as every other service, so an unusual destination doesn't become an unmonitored blind spot.

💾 Custom Connector Registration

{
  "connector_name": "regional_pos_sync",
  "owning_team": "commerce-integrations",
  "subscribed_events": ["order.completed"],
  "delivery_protocol": "proprietary_pos_api_v2",
  "container_image": "cxos/connectors/regional-pos-sync:1.4.0"
}

🔗 Integration Points

• Azure Service Bus — event subscription mechanism shared with every standard destination
• Shared connector template — the scaffold every custom connector starts from
• Application Insights / Azure Monitor — standard observability every connector inherits
• Query & Analytics Engine — common read path when a connector needs lakehouse data beyond the triggering event

🧰 Services Consumed

• Owning microservice — Cxos.Activation.Api (see the Full Application Service Map)
• Database — Azure Cosmos DB (dispatch log) + Azure Cache for Redis (frequency caps)

⚠️ Non-Functional Considerations

• Scale: each custom connector is sized to its own destination's needs — no shared infrastructure bottleneck across unrelated connectors
• Latency: varies per connector's use case, documented individually rather than held to one platform-wide SLA
• Reliability: inherits the same retry/dead-letter conventions as standard destinations by building on the shared template rather than reinventing them
• Security/Privacy: each custom connector goes through the same Governance & Security review as a standard destination before being granted event subscriptions

🎯 Enterprise Example

A regional point-of-sale vendor requires a proprietary, non-REST protocol no standard connector supports. Commerce Integrations scaffolds a custom connector from the shared template in a few days, inheriting retry logic and monitoring for free, rather than building an integration from scratch.