APIs & Webhooks

💼 Business Context

• Not every integration justifies a purpose-built connector — a configurable, low-code path keeps time-to-onboard short for long-tail systems
• Reduces engineering backlog for one-off or low-volume integrations
• Owned by Data / Platform Engineering, used on behalf of whichever team needs the integration

🔌 Technical Overview

The Generic Connector Framework is a .NET Core microservice that exposes two integration modes: an outbound REST client, configured with a base URL, auth scheme, and a field-mapping definition (JSON) that maps the source API's response to the shared ingestion contract; and an inbound webhook receiver (an Azure Function) that accepts a configurable payload shape and the same field-mapping definition. Both modes ultimately call Cxos.Ingestion.Client, so a new source can be onboarded via configuration rather than a new codebase.

💾 Sample Connector Configuration

{
  "connector_id": "conn_partner_survey",
  "mode": "webhook",
  "auth": { "type": "hmac", "header": "X-Signature" },
  "field_mapping": {
    "event": "$.event_type",
    "user_id": "$.customer.external_id",
    "properties.score": "$.survey.nps_score"
  }
}

🔗 Integration Points

• Generic Connector Framework — .NET Core microservice (REST client + webhook receiver modes)
• Cxos.Ingestion.Client NuGet package — shared contract, called by every configured connector instance
• Azure Key Vault — per-connector credential storage
• Azure API Management — inbound webhook endpoint exposure and throttling

🧰 Services Consumed

• Owning microservice — Cxos.Connectors.Generic (see the Full Application Service Map)
• No dedicated database — stateless connector (see Platform Connectors above)

⚠️ Non-Functional Considerations

• Scale: each connector instance is independently rate-limited and scaled, so one noisy integration can't starve another
• Latency: webhook mode is near-real-time; polling mode latency is configurable per connector (typically 5-60 minutes)
• Reliability: field-mapping validation runs at configuration time, not at runtime, to catch mapping errors before they cause data loss
• Security/Privacy: every connector instance is scoped to its own Key Vault secret and least-privilege access; mapping configuration is reviewed before a new source goes live

🎯 Enterprise Example

A partner loyalty program has no dedicated CXOS connector but exposes a webhook on survey completion. Standing up the integration via the Generic Connector Framework's field-mapping configuration takes an afternoon instead of a multi-week engineering project, and NPS scores start flowing into the unified profile the same day.