Delivery and retries

A delivery succeeds when your endpoint answers with any 2xx status within 15 seconds. Every other outcome is a failure, and whether Atlas tries again depends on the kind of failure.

• Retried: a 5xx status, 408, 429, no answer within 15 seconds, or a network or connection error. These are usually temporary. With a 429 or 503, a retry-after header, in seconds or as a date, holds the next attempt back for as long as it says, up to 24 hours, and never sooner than the schedule below, so a short or zero value does not bring a retry forward.
• Final at once: any other 4xx status, and any redirect. A 4xx usually means the request will never be accepted as it stands, so repeating it would only add load. Atlas does not follow redirects: point the webhook at the final address instead.

Atlas makes up to 8 attempts. Each wait is counted from the attempt before it, and every attempt is signed again when it is sent, so its timestamp is always current.

The last attempt comes 34 hours and 42 minutes after the first. If it fails too, the delivery is marked dead and kept in your delivery log, where you can replay it once your endpoint is working.

When every delivery to a webhook has failed for three days, counted from the first failure after its last successful delivery, Atlas pauses the webhook. Nothing more is sent to it until someone turns it back on, so a broken endpoint does not collect failures indefinitely.

Atlas emails the escalation contact set on the webhook, or, when there is none, every owner and administrator of the workspace. The email names the webhook, the address it points to, the last answer from your endpoint, and when the failures began. The pause is also recorded in the audit log.

Settings, then Webhooks, marks the webhook as paused and turns it back on in one step. Through the API, a paused webhook carries pausedAt; sending { "disabled": false } to PATCH /v1/webhooks/{id} resumes it and clears the field. Replay the deliveries you still need from the delivery log once your endpoint is working.

Atlas records every change before it sends the webhook for it. If a delivery was not queued at that moment, for example because a server restarted between the two, Atlas finds the change on its next check, which runs every minute, and queues the event then. After a restart it checks the previous 24 hours. The recovered event has the same Atlas-Event-Id it would have had, so a receiver that deduplicates on the event id processes it once.

Recovery never sends a webhook an event from before you created or last changed it, so a new, edited, or resumed webhook starts from its own moment.

Atlas records every delivery: the request it sent, your response, how long it took, how many attempts it has made, and when the next one is due. Read the log for one webhook or for the whole workspace, or open it from the webhook's page in Settings.

GET /v1/webhooks/{id}/deliveries?limit=50   # one webhook
GET /v1/webhook-deliveries?limit=50         # every webhook in the workspace

Use replay to send a past delivery again, for example after you fix your receiver. The replay is a new delivery with its own delivery id, and it carries the original event with the original event id, signed at the moment it is sent. Use test-delivery to send a subscription.test event and confirm that your endpoint is reachable and verifies signatures.

POST /v1/webhooks/{id}/deliveries/{deliveryId}/replay   # send a past delivery again
POST /v1/webhooks/{id}/test-delivery                     # send a subscription.test event

Both need a token with the webhooks:manage scope. The request and response shapes are in the webhooks API reference.

Give each webhook an owner and an escalation contact, so that anyone who sees a failing delivery knows whom to ask. Set ownerLabel, escalationEmail, and escalationNote when you create or update the webhook. Atlas shows them beside the webhook and its deliveries.