Reliability
Your endpoint will be unavailable at some point. This page is the numbers you need to design for that: how long you have to recover, what you lose if you do not, and what arrives twice or late when you do.
Retries
| Attempts per delivery | 12, including the first |
| Backoff | exponential, capped at 6 hours |
| Request timeout | 10 seconds |
| Email alert | after 5 consecutive failures on an endpoint |
| Auto-pause | after 50 consecutive failures on an endpoint |
A delivery is retried when your endpoint returns a non-2xx status, when the connection fails, or when it does not answer within 10 seconds.
Answer fast and do the work later. The timeout is on your whole response,
so an endpoint that processes synchronously can fail on load alone. Return
2xx as soon as you have stored the event, and process it afterwards.
Duplicates
Delivery is at-least-once. You will receive the same event more than once, and not only when something is wrong: a response we never saw is retried even though your endpoint handled it.
Deduplicate on the envelope’s id, which is stable across every retry of the
same event:
if store.seen(event["id"]):
return 200
store.record(event["id"])
process(event)
Record the id before you act, in the same transaction where possible. The failure this avoids is processing an event, crashing before recording it, and processing it again on the retry.
Do not deduplicate on created, on a message id, or on the payload: several
distinct events can share all three.
Ordering
So delivery.delivered can arrive before the delivery.deferred that
preceded it, and a bounce can arrive after you believed the message settled.
Design for it rather than hoping. Two approaches, and the second is usually right:
Use created, the envelope’s Unix seconds, to discard an update older
than the state you hold. Cheap, and sufficient when you only track a latest
status.
Treat each event as a fact rather than a transition. Record that a bounce happened, rather than moving a state machine from “delivered” to “bounced”. Facts commute; transitions do not.
When your endpoint fails
Five consecutive failures sends an email to the account’s alert address, once per streak rather than per failure.
Fifty consecutive failures pauses the subscription. A paused webhook receives nothing, and the pause is visible on the dashboard. Resume it by updating the webhook; new events flow again from that moment.
Events raised while paused are not queued for you. They are in the event log for 7 days, which is the only way back.
A streak is consecutive: one success resets it, so an endpoint that is flapping can stay unpaused indefinitely while losing individual events to the 12-attempt limit. Watch for the alert mail rather than relying on the pause to tell you something is wrong.
What to return
| 2xx | Accepted. Nothing is retried |
| anything else | Retried, up to the limit |
| no response in 10s | Retried |
Return 2xx even for an event you do not care about or cannot parse.
A non-2xx means “try again”, and retrying will not make an unrecognised event
recognisable; it just spends your 12 attempts and moves you toward a pause.