MermanDraw
Open Editor

Mermaid exampleSequence Diagram

Webhook Delivery Sequence Diagram with Retries and Backoff

Webhooks look trivial until the first customer endpoint goes down for an afternoon. This diagram is the delivery contract you publish in your developer docs: how payloads are signed, how many times you retry, how long you wait, and what happens when you give up.

  • webhook retry diagram
  • exponential backoff sequence diagram
  • webhook signature
  • mermaid loop alt example
Webhook Delivery Sequence Diagram with Retries and BackoffCustomer endpointWorkerDelivery queueYour serviceCustomer endpointWorkerDelivery queueYour servicealt[2xx within 10s][Timeout or 5xx]loop[Up to 5 attempts, backoff 1m, 5m,30m, 2h, 12h]4xx responses are not retriedEnqueue event order.paidDequeue jobSign payload with HMAC-SHA256 and timestampPOST /webhooks with X-Signature header200 OKMark delivered503 or no responseSchedule next attemptAfter final failure, disable endpoint and notify customer
Open in editor → 20 linesrenders in GitHub, Notion, Obsidian

Mermaid code

sequenceDiagram
    participant S as Your service
    participant Q as Delivery queue
    participant W as Worker
    participant E as Customer endpoint
    S->>Q: Enqueue event order.paid
    Q->>W: Dequeue job
    W->>W: Sign payload with HMAC-SHA256 and timestamp
    loop Up to 5 attempts, backoff 1m, 5m, 30m, 2h, 12h
        W->>E: POST /webhooks with X-Signature header
        alt 2xx within 10s
            E-->>W: 200 OK
            W->>Q: Mark delivered
        else Timeout or 5xx
            E-->>W: 503 or no response
            W->>Q: Schedule next attempt
        end
    end
    Note over W,E: 4xx responses are not retried
    W->>S: After final failure, disable endpoint and notify customer

Paste this into any tool that renders Mermaid, or into the editor to change the theme and export PNG or SVG. Syntax reference: Sequence Diagram guide.

What this diagram shows

The Your service lane enqueues an order.paid event; a Worker picks it up and signs the payload with an HMAC and a timestamp so the receiver can reject replays. The loop block carries the retry policy in its label: five attempts with a backoff schedule from one minute to twelve hours. Inside, an alt splits on a 2xx within ten seconds versus a timeout or 5xx. The note states the rule people most often get wrong: 4xx means the request itself is bad, so retrying is pointless. The final message shows the escalation after the last attempt.

Putting the policy numbers in the diagram rather than in surrounding prose means the diagram can be pasted into a support reply and still answer the question.

How to adapt it

  • Replace the backoff schedule in the loop label with your real one; keep the total window visible so customers can plan their outage tolerance.
  • Add a break block inside the success branch if you want to show the loop ending early, or leave it implicit as here.
  • Add a participant D as Dashboard lane and a message to it when the endpoint is disabled, if customers can re-enable it themselves.
  • Change order.paid to the event your integration guide uses first; a familiar event name makes the diagram instantly relevant.

FAQ

How do I show that retries stop after a success?

Use a break block around the success case: break Delivered with the mark-delivered message inside. Mermaid draws it as a labelled frame that signals the loop exits there.

Should the signature step be a self-message or a note?

A self-message (W->>W) when it is work the worker does, as here. A note when it is a fact about the data, for example Note right of W: Signature covers timestamp and body.