Webhook delivery, retry, and dead-letter flow

This webhook delivery flowchart analyses the handling of a single POST and the measures put in place to make it reliable: a 2xx is delivered, a 4xx client error is not retried, and a timeout or 5xx waits with backoff until retries are gone. Exhausted deliveries land on a dead-letter queue; an operator can replay, which re-signs the payload rather than POSTing the old body, or abandon the event.

People draw this one while implementing a subscriber contract, to explain why a 400 must not tight-loop, or to show where replay actually starts. The flow splits at the response, and this is the crux: treating every failure as retryable allows a bad payload to impair both the subscriber and the remote service, and a flow without a dead-letter path has no way to resolve unexpected blockages.

Open in editor

Mermaid source

---
title: Webhook delivery, retry, and dead-letter flow
---
flowchart LR
  event([Domain event]) --> sign[Sign payload]
  sign --> post[POST to endpoint]
  post --> resp{Response?}
  resp -->|2xx| done([Delivered])
  resp -->|4xx client error| failed([Do not retry])
  resp -->|timeout or 5xx| attempts{Retries left?}
  attempts -->|Yes| wait[Wait with backoff]
  wait --> post
  attempts -->|No| dlq[(Dead-letter queue)]
  dlq --> ops[Operator inspects]
  ops --> replay{Replay?}
  replay -->|Yes| sign
  replay -->|No| giveup([Abandoned])

Stock Mermaid vs Line9 on this webhook delivery flow

Run the same source through the stock Mermaid engine and it often will not look as good. In some cases, Mermaid is able to deliver a usable graph, but not always. On this one:

The same webhook delivery flow through stock Mermaid — a long Wait-to-POST return and a longer Replay-to-Sign arc along the bottom, with labels mid-edge — Stock Mermaid · same source View full size ↗

The stock Mermaid renderer positions ‘Wait with backoff’ to the right of ‘Retries left?’, rather than closer to ‘POST to endpoint’. This goes against the direction of flow, causing the diagram to appear more untidy and results in the unnecessary crossing of edges. Line9 keeps the wait-and-retry loop under the POST node so the flow is far easier to read.

For a fuller product comparison — layout, export, CLI, and pricing — see Line9 vs mermaid.live.

Render your own

Paste any Mermaid flowchart into the free online editor — no account needed. Prefer the terminal? Install the line9 CLI (free for personal use).

More scenarios on the Mermaid examples hub.

Mermaid source

Stock Mermaid vs Line9 on this webhook delivery flow

Render your own

Related diagrams