Endpoint states
The four states of a webhook endpoint, the transitions between them, and what each does to deliveries in flight.
An endpoint has a state and, separately, a testStatus.
state | Receives new events | Meaning |
|---|---|---|
pending | No | Registered, not yet enabled. |
active | Yes | Enabled after a passed test. |
disabled | No | Stopped; can be enabled again. |
revoked | No | Retired permanently. Terminal. |
testStatus | Meaning |
|---|---|
untested | No test since registration or since the URL last changed. |
passed | The last test delivery got a 2xx. |
failed | The last test delivery did not. |
Transitions
flowchart LR
P[pending] -- enable after passed test --> A[active]
P -- disable --> D[disabled]
A -- disable --> D
D -- enable after passed test --> A
P -- revoke --> R[revoked]
A -- revoke --> R
D -- revoke --> R
- Enable requires
testStatuspassed. You can test in any non-revoked state. - Disable is allowed from any non-revoked state.
- Changing the URL is allowed in
pendinganddisabledonly, and resetstestStatustountested, so the endpoint must pass a new test before it is enabled again. - Revoke is allowed from any non-revoked state. It also revokes every signing secret of the
endpoint. A revoked endpoint refuses every further change with
409 WEBHOOK_ENDPOINT_REVOKED.
Every transition requires the current revision in If-Match and is recorded in your organization's
audit log. See Register and manage endpoints for the routes.
What happens to deliveries in flight
Only active endpoints receive new deliveries: an event that occurs while the endpoint is in any
other state creates no delivery for it, and is not delivered later when the endpoint becomes active.
Deliveries that were already pending on the retry ladder are checked again before each attempt:
| Endpoint state at the next attempt | Effect on a pending delivery |
|---|---|
active | The attempt is sent. |
pending or disabled | Settles dead with reason ENDPOINT_DISABLED; nothing is sent. |
revoked | Settles dead with reason ENDPOINT_REVOKED; nothing is sent. |
An attempt already in progress when you disable or revoke the endpoint completes normally.
Deliveries that went dead because the endpoint was disabled are not revived by enabling it again.
Once the endpoint is active, replay them: one at a time, or all of them
with a batch replay. A revoked endpoint's deliveries cannot be replayed, since replay requires an
active endpoint; they remain visible in the delivery log for 30 days.