Retries & auto-disable
What Listener does when your endpoint is slow, down or failing, and how to recover.
2 min read
What counts as success#
A delivery succeeds when your endpoint returns any 2xx status within 10 seconds. Everything else is a failure: 3xx (redirects are not followed), 4xx, 5xx, timeouts, TLS errors and refused connections.
Retry schedule#
Failed deliveries are retried with increasing delays after the first attempt:
| Attempt | Delay after the previous attempt |
|---|---|
| 2 | 1 minute |
| 3 | 5 minutes |
| 4 | 30 minutes |
| 5 | 2 hours |
| 6 | 5 hours |
| 7 and later | 10 hours |
Retries continue while the next attempt still falls within three days of the event, up to 12 attempts in all. After that the delivery is marked failed and not tried again automatically.
Because of retries, the same event can arrive more than once, and events can arrive out of order. See Best practices.
Automatic disabling#
If an endpoint has had no successful delivery for three days while its deliveries keep failing, Listener disables it: its status becomes disabled with disabled_reason: "failing", and nothing more is sent to it. A single success resets the clock. (Endpoints you pause yourself show disabled_reason: "manual".)
To recover:
- Fix the endpoint, and confirm it with
POST /v1/webhook-endpoints/{id}/test. - Re-enable it with
PATCH /v1/webhook-endpoints/{id}and{"disabled": false}. - Catch up on what you missed with the Events API: list events since the outage with
created_gte, and process the ones you have not seen. Events are kept for 30 days.
Inspecting deliveries#
GET /v1/webhook-endpoints/{id}/deliveries lists recent deliveries with their status (pending, succeeded or failed), every attempt, your endpoint’s response code, the first 1 KB of its response body, the latency and, when it failed before getting a response, an error such as timeout or connection_failed. The Webhooks tab in the app shows the same log.
To send one again right now, for example after a fix, call POST /v1/webhook-deliveries/{id}/retry. The attempt runs immediately; if it fails, a pending delivery keeps its original schedule.