Skip to main content

Delivery and retries

Delivery guarantees​

  • At least once: an event can be delivered more than once. Deduplicate events with the webhook-id header.
  • 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):

AttemptDelay after the previous attempt
1immediately
25 seconds
35 minutes
430 minutes
52 hours
65 hours
710 hours
814 hours
920 hours
1024 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.