Made in 10Docs
GuidesAPI
Webhooks

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.

Answer first, work after
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.

TryAfter the one before
230 seconds
32 minutes
410 minutes
51 hour
66 hours
7 to 1112 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

GET/v1/webhooks/{webhook_id}/deliveries

What was sent to one endpoint, newest first: { "data": [...], "has_more": false }, paged with limit and before (a created_unix).

Delivery
{
  "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
}
statusWhat it means
pendingWaiting for its next try (next_attempt_unix)
pausedIts endpoint is off: it goes when the endpoint is turned back on
deliveredYour endpoint answered 2xx
failedOut of tries. It can still be replayed

last_status_code and last_error say what happened on the last try.

Replay a delivery

POST/v1/webhooks/deliveries/{delivery_id}/retry

The 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.

Coming soonAn email when an endpoint is turned off

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.

On this page