Webhook endpoint states and delivery log reference
This page documents the WebhookEndpoint.status values, the WebhookDelivery.status values, the derived Retrying banner, the delivery-stopped email, HMAC signature headers, retry behavior, and the replay window.
Endpoint status values (WebhookEndpoint.status)
Section titled “Endpoint status values (WebhookEndpoint.status)”The endpoint lifecycle has exactly three stored states.
| Status | Meaning | Recovery |
|---|---|---|
active |
Delivering payloads | — (healthy) |
paused |
Delivery temporarily disabled by an admin | Admin selects Resume (webhook_endpoints_update) |
failing (shown as Delivery stopped) |
A delivery to this endpoint became dead — its sixth attempt failed, the receiver answered 410 Gone, or MapleGather stopped before it recorded the result of the delivery’s last attempt — so delivery to the endpoint has stopped. New events are not sent to it and are not kept to send later; retries already scheduled for it are not sent |
Admin fixes receiver, then selects Re-enable (webhook_endpoints_update with status: active). Nothing is resent automatically — replay the deliveries you need |
The delivery-stopped email. When an endpoint moves from active to failing, MapleGather emails every active admin of your organization whose role includes View webhooks (webhooks:read), up to 10; invited admins, and admins whose role cannot view webhooks, are not emailed. The email names the endpoint by a masked URL (its scheme and host, then … and the last four characters; the path and query, which can carry a receiver’s secret, are never emailed), the event type of the delivery that stopped it, how it ended (all six attempts failed, with the last HTTP status or “no HTTP response”; or a 410 Gone), and where to re-enable the endpoint. It is sent once per stop — a second delivery dying while the endpoint is already stopped sends nothing — and there is no configurable failure threshold: deliveries that fail and then succeed on a retry never send an email. A delivery replayed to a debug URL never stops the endpoint.
The Retrying banner is not a status. When an active endpoint’s delivery log holds failed deliveries (no 2xx yet, a retry scheduled), the endpoint detail shows a Retrying banner as an early warning. It is computed from the loaded log, not stored, sends no email, and no longer shows once those deliveries succeed and the log is reloaded.
Delivery status values (WebhookDelivery.status)
Section titled “Delivery status values (WebhookDelivery.status)”The log keeps one row per delivery: each attempt updates that row’s attempt number, status and response. A replay creates a new row (attempt 1).
| Status | Meaning | responseStatus |
nextAttemptAt |
|---|---|---|---|
pending |
Queued; the first attempt has not finished | null |
null |
delivered |
Endpoint returned 2xx |
the HTTP status | null |
failed |
No 2xx (an error status, or no HTTP response) and a retry is pending |
the HTTP status, or null when there was no response |
set (next retry time) |
dead |
No more attempts will be made — terminal. Either the sixth attempt failed, the endpoint answered 410 Gone, the endpoint was paused or stopped when the next attempt came due, or MapleGather stopped before it recorded the result of the delivery’s last attempt (for example, the server sending it stopped mid-attempt; whether that attempt reached your receiver is not known) |
last HTTP status recorded, or null |
null |
When a delivery becomes dead because its sixth attempt failed, because of a 410 Gone, or because MapleGather stopped before it recorded the result of the last attempt, the endpoint’s status becomes failing (Delivery stopped) and the email above is sent. A delivery that becomes dead because the endpoint was already paused or stopped changes nothing else. A dead delivery can still be replayed within its 30-day window.
Retry schedule
Section titled “Retry schedule”MapleGather makes up to 6 attempts per delivery over about a day, with growing gaps between attempts. Return any 2xx to acknowledge receipt. 410 Gone ends delivery at once and stops the endpoint; any other status, or no response within 10 seconds, triggers a retry.
HMAC signature headers
Section titled “HMAC signature headers”Every delivery includes:
| Header | Value |
|---|---|
X-Webhook-Signature |
HMAC-SHA256 hex digest of <X-Webhook-Timestamp>.<raw request body>, using the endpoint’s signing secret |
X-Webhook-Timestamp |
Unix timestamp (seconds) of when the delivery was dispatched |
Replay tolerance: reject deliveries where X-Webhook-Timestamp is more than five minutes in the past. This is the replay-defense window. Note that replayed deliveries regenerate the signature at the current timestamp, so your five-minute window does not reject legitimate replays.
Replay window
Section titled “Replay window”Deliveries can be replayed within 30 days of their original dispatch. Replaying a delivery older than 30 days returns 409 conflict.past_replay_window. Replay regenerates the HMAC signature at the current timestamp.