Delivery and retries
Delivery guarantees
- At least once: an event can be delivered more than once. Deduplicate events with the
webhook-idheader. - No ordering: events can arrive out of order. Because payloads are lean and you fetch the current state, this is harmless.
Retries
A delivery is successful when your endpoint responds with a 2xx status code within 15 seconds.
Everything else (other status codes, redirects, timeouts, connection errors) is retried with the following schedule (with a small random jitter):
| Attempt | Delay after the previous attempt |
|---|---|
| 1 | immediately |
| 2 | 5 seconds |
| 3 | 5 minutes |
| 4 | 30 minutes |
| 5 | 2 hours |
| 6 | 5 hours |
| 7 | 10 hours |
| 8 | 14 hours |
| 9 | 20 hours |
| 10 | 24 hours |
After the last attempt (about 3 days) the event is dropped.
If your endpoint responds with a Retry-After header, the next attempt waits at least that long.
Disabling
- If your endpoint responds with
410 Gone, the webhook is disabled immediately. - If all deliveries to a webhook fail for 3 days, the webhook is disabled.
A disabled webhook shows as inactive in CargoApps. Fix your endpoint and reactivate it with the toggle. Events that happened while it was disabled are not sent.
Notifications
The notification emails of a webhook receive an email:
- when the webhook starts failing: the first failed delivery after the webhook was created or after a successful delivery. You get one email per failure period, so you can fix your endpoint before the webhook is disabled.
- when the webhook was disabled automatically (
410 Gone, or failing for 3 days).
Pausing or reactivating a webhook yourself does not send an email.
Delivery log
In CargoApps, the Deliveries tab lists the deliveries of the last 14 days, newest first, and can be filtered by webhook and status. It shows the event, status (delivered, retrying, failed), number of attempts and the response of the last attempt (status code or error, e.g. a timeout).
Click a delivery to see its details: the event ID (webhook-id), the times of the attempts, the request body, and the response of the last attempt, including the first 10 KB of the response body. A short error message in your response body makes failed deliveries easier to debug.
The webhooks table also shows the result of the last delivery attempt of each webhook.