Webhooks

💼 Business Context

• Webhooks are how most SaaS platforms (Shopify, SendGrid, Zendesk) natively notify external systems — supporting them well is table stakes for connector coverage
• Near-real-time by nature, since the source platform pushes the moment something happens
• Owned by Platform Engineering, with one receiver per connector

🔌 Technical Overview

Each webhook-based connector registers its own Azure Function endpoint (e.g., /webhooks/shopify, /webhooks/sendgrid), independently deployed and scaled. Every receiver follows the same pattern: verify the platform's signature (HMAC or equivalent), map the platform-specific payload to the shared event contract, and call Cxos.Ingestion.Client — the same pattern used across every webhook-driven integration described elsewhere in this handbook.

💾 Webhook Receiver Skeleton

[Function("ShopifyWebhook")]
public async Task Run(
    [HttpTrigger("post")] HttpRequestData req)
{
    VerifyHmac(req, _shopifySecret);
    var order = await ParseAsync(req.Body);
    await _cxosClient.TrackAsync(MapOrderEvent(order));
    return req.CreateResponse(HttpStatusCode.OK);
}

🔗 Integration Points

• One Azure Function per source platform, independently deployed
• Platform-specific signature verification (HMAC, etc.) before payload processing
• Cxos.Ingestion.Client NuGet package — shared contract for the outbound call
• Azure API Management — public webhook endpoint exposure and throttling

🧰 Services Consumed

• Owning microservice — Cxos.Ingestion.Api (see the Full Application Service Map)
• Database — Azure Cache for Redis (cache only)

⚠️ Non-Functional Considerations

• Scale: Azure Functions consumption plan scales each receiver independently based on that platform's traffic pattern
• Latency: near-real-time — events land within seconds of the source platform's push
• Reliability: idempotent handling (event_id dedup) since most platforms retry webhook deliveries on failure
• Security/Privacy: signature verification happens before any payload is trusted or parsed

🎯 Enterprise Example

SendGrid, Zendesk, and Shopify all push events to their own dedicated webhook receivers. When Shopify has a traffic spike during a flash sale, its receiver scales independently without affecting SendGrid's or Zendesk's — each platform's integration is isolated.