Webhook Delivery Flow: Mermaid Sequence Diagram

About Source

A webhook delivery flow describes how a platform notifies an external system about an event — by making an outbound HTTP POST request to a pre-configured URL — including payload signing for authenticity verification and the acknowledgement protocol.

What the diagram shows

This sequence diagram traces webhook delivery from event emission to consumer acknowledgement across four participants: Source System (the platform emitting events), Webhook Dispatcher (the delivery worker), Signing Service (HMAC payload signing), and Consumer Endpoint (the subscriber's HTTP server).

1. Event occurs: a business event fires in the source system — e.g., payment.succeeded, user.created, or order.shipped. 2. Event persisted: the event is persisted to an outbox table or event store before dispatch begins, guaranteeing at-least-once delivery even if the dispatcher crashes. 3. Dispatch queued: the webhook dispatcher picks up the event from the outbox. 4. Payload signed: the dispatcher generates an HMAC-SHA256 signature of the JSON payload using a per-consumer secret key and includes it in the X-Webhook-Signature header. 5. HTTP POST delivered: the dispatcher sends a POST to the consumer's registered endpoint with the signed payload. 6. Consumer validates signature: the consumer recomputes the HMAC and compares it to the header — rejecting the request if they don't match (prevents spoofed webhooks). 7. 2xx acknowledgement: the consumer processes the event and returns a 200 OK within the timeout window (usually 5-30 seconds). 8. Failure path: non-2xx responses or timeouts trigger the retry strategy — see Webhook Retry Strategy.

Why this matters

Webhooks invert the polling model: instead of your system repeatedly asking "did anything happen?", the source system pushes events as they occur. Payload signing is essential — without it, anyone who knows your webhook URL can send fake events. The outbox pattern guarantees no events are lost between the business transaction and delivery.

Frequently asked questions

A webhook delivery flow describes how a platform notifies an external system about an event by making an outbound HTTP POST to a pre-configured URL. The source system emits an event, persists it to an outbox for reliability, signs the payload with HMAC-SHA256, delivers it to the consumer's endpoint, and expects a 2xx acknowledgement within a timeout window.

The webhook dispatcher generates an HMAC-SHA256 signature by hashing the JSON payload using a per-consumer secret key and includes it in a header such as `X-Webhook-Signature`. The consumer recomputes the HMAC using the same shared secret and compares it to the header value. If they match, the payload is authentic and unmodified. If they don't match, the consumer rejects the request — preventing spoofed or tampered webhook deliveries.

Use webhooks when near-real-time event notification is needed and you want to push events as they occur rather than having consumers repeatedly poll an API for changes. Webhooks are more efficient for the source system (no polling overhead) and provide lower latency for consumers. Polling is better when consumers are behind firewalls that block inbound HTTP, or when eventual consistency with a few minutes of delay is acceptable.

The most critical mistake is not persisting the event before attempting delivery — if the dispatcher crashes between the business transaction and the HTTP POST, the event is lost. Without an outbox pattern or event store, at-least-once delivery cannot be guaranteed. Another mistake is not validating signatures on the consumer side, leaving the endpoint open to forged payloads. Teams also frequently set timeouts too long (30+ seconds), blocking the dispatcher thread unnecessarily when a consumer is slow.

mermaid

sequenceDiagram
    participant SS as Source System
    participant WD as Webhook Dispatcher
    participant SG as Signing Service
    participant CE as Consumer Endpoint

    SS->&gt;SS: Business event occurs
    SS->&gt;SS: Persist event to outbox table
    WD->&gt;SS: Poll outbox for pending events
    SS-->&gt;WD: Event payload (event-id, type, data)
    WD->&gt;SG: Sign payload with consumer secret
    SG->&gt;SG: Compute HMAC-SHA256 signature
    SG-->&gt;WD: Signature string
    WD->&gt;CE: POST /webhook (X-Webhook-Signature: sig, JSON body)
    CE->&gt;CE: Recompute HMAC and compare signature
    alt Signature invalid
        CE-->&gt;WD: 401 Unauthorized
        WD->&gt;WD: Mark delivery failed - do not retry (bad config)
    else Signature valid
        CE->&gt;CE: Process event idempotently
        alt Processing succeeds
            CE-->&gt;WD: 200 OK
            WD->&gt;SS: Mark event delivered in outbox
        else Processing fails or timeout
            CE-->&gt;WD: 500 or no response
            WD->&gt;WD: Schedule retry with backoff
        end
    end