Webhook Retry Sequence
The code
sequenceDiagram
autonumber
participant P as Payment Provider
participant L as Listener Endpoint
participant Q as Retry Queue
P->>L: POST webhook event
alt Endpoint returns 200
L->>Q: Mark event processed
else Endpoint times out
P->>Q: Enqueue for redelivery
loop every 5 min
Q->>L: Replay webhook event
L-->>Q: Acknowledge delivery
end
end
Note over P,Q: Retries stop after 24 hours
How this template works
This template documents the contract behind webhook delivery: a provider POSTs an event to your endpoint, and what happens next depends entirely on whether your endpoint answers in time. The success branch marks the event processed; the timeout branch enqueues it for redelivery, and a replay loop keeps trying on a schedule until the endpoint acknowledges or the retry window closes. Integration engineers use this diagram in provider documentation and in runbooks, because “we never got your webhook” arguments end the moment both sides agree on this picture.
The syntax combines the two block types you will use most. Three lifelines are declared first: participant P as Payment Provider, participant L as Listener Endpoint, and participant Q as Retry Queue. The delivery P->>L: POST webhook event is the only unconditional message. Then alt Endpoint returns 200 opens the success branch, where L->>Q: Mark event processed records the outcome. The else Endpoint times out branch contains the interesting part: P->>Q: Enqueue for redelivery hands the event to the queue, and loop every 5 min opens a repetition block containing the replay Q->>L: Replay webhook event and its dashed acknowledgment L-->>Q: Acknowledge delivery. The loop label is free-form text, so “every 5 min” renders exactly as written. Both the alt and the loop close with their own end, and the final Note over P,Q: Retries stop after 24 hours spans all three lifelines to record the giving-up policy.
The gotcha is nested block closers. This diagram has two blocks and therefore two end lines — one for the loop, one for the alt — and they must appear in reverse order of opening. When editing, add one block at a time and re-render, because a missing or extra end shifts every subsequent message into the wrong branch without producing an obvious error. The second trap is putting the acknowledgment outside the loop; then the diagram claims the endpoint is contacted exactly once.
To adapt it, change the loop label to your real backoff schedule, add a signature verification message before processing, or add a dead-letter branch after the retry window closes.
Related templates: the fault handling flowchart draws the same retry logic as a decision flow, the payment processing sequence shows the checkout that generates these webhook events, and the microservice call sequence covers the internal consumers that process the event. The sequence diagram guide documents alt, else, and loop syntax.
