Delivery and retries
What counts as delivered, when a delivery is tried again, replaying one, and when an endpoint is turned off.
A webhook is delivered when your endpoint answers 2xx. Anything else is tried again, on a widening schedule, for about three days. Every attempt is kept for 30 days, so you can see what happened and send any of them again.
Answer quickly
Answer 2xx within 10 seconds, then do the slow work. Check the signature, store the event, answer, and process it afterwards.
app.post("/hooks/calls", express.raw({ type: "application/json" }), (req, res) => {
const body = req.body.toString("utf8");
if (!verifyWebhook(process.env.WEBHOOK_SECRET, req.headers, body)) return res.sendStatus(400);
res.sendStatus(204); // within 10 seconds
queue.add(JSON.parse(body)); // the slow work, after answering
});Redirects aren't followed: a 3xx counts as a failure. Use the address it redirects to.
Retries
Anything but a 2xx is tried again: another status, no answer within 10 seconds, a refused connection, a certificate we don't accept.
| Try | After the one before |
|---|---|
| 2 | 30 seconds |
| 3 | 2 minutes |
| 4 | 10 minutes |
| 5 | 1 hour |
| 6 | 6 hours |
| 7 to 11 | 12 hours each |
That is 11 tries in all, the last about 67 hours after the first. Then the delivery is failed; it can still be replayed.
An address that points inside a network by the time of sending (its DNS changed) fails at once, without retries: nothing is sent there.
At least once, in no guaranteed order
A retry or a replay can bring the same event twice, and events can arrive out of order. Dedupe on the webhook-id header. When an event and GET /v1/calls/{call_id} disagree, the GET is right.
Deliveries
/v1/webhooks/{webhook_id}/deliveriesWhat was sent to one endpoint, newest first: { "data": [...], "has_more": false }, paged with limit and before (a created_unix).
{
"id": "whd_5Hs9Fk2PvX7nCb1QzW4r",
"endpoint_id": "whe_6Tn1Vb8XcK3mPq9LsD2f",
"event_id": "evt_3Kp8Zr1WqN6xBv4MhS9a",
"event_type": "call.ended",
"status": "pending",
"attempts": 1,
"next_attempt_unix": 1793300130,
"last_attempt_unix": 1793300100,
"last_status_code": 500,
"last_error": "it answered 500",
"delivered_unix": null,
"created_unix": 1793300100
}status | What it means |
|---|---|
pending | Waiting for its next try (next_attempt_unix) |
paused | Its endpoint is off: it goes when the endpoint is turned back on |
delivered | Your endpoint answered 2xx |
failed | Out of tries. It can still be replayed |
last_status_code and last_error say what happened on the last try.
Replay a delivery
/v1/webhooks/deliveries/{delivery_id}/retryThe same event, with the same webhook-id, goes again now. A delivered or failed one starts a fresh schedule; one waiting for its next try goes now instead. It answers the delivery.
While its endpoint is off, a replay is 409 webhook_disabled: turn the endpoint back on instead, which sends everything that waited.
Because a replay keeps its webhook-id, a receiver that dedupes will ignore an event it already took.
When an endpoint keeps failing
Five days of failures, with no success in between, turn the endpoint off: its enabled becomes false, with disabled_reason: "failing" and failing_since_unix set. Nothing is lost meanwhile: its events wait (paused) for up to the 30 days they are kept.
To turn it back on, fix the endpoint, then PATCH /v1/webhooks/{webhook_id} with { "enabled": true }. Everything that waited goes at once. Changing its url gives it a fresh start on failures.
Nobody is told yet when an endpoint is turned off. Watch enabled and disabled_reason on your endpoints, or the deliveries list, in the meantime.
How long we keep them
Events and their deliveries are kept for 30 days, then deleted.