Webhook endpoint states and delivery log reference
This page documents the WebhookEndpoint.status values, the WebhookDelivery.status values, the derived failing-health badge, 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) |
dead |
Retry budget exhausted (6 attempts over ~24 hours) — payloads moved to the dead-letter queue | Admin fixes receiver, then selects Re-enable (webhook_endpoints_update) |
“Failing” is not a fourth status. When an active endpoint’s recent deliveries start returning non-2xx responses, the UI shows a derived failing health badge on that endpoint as an early warning — before the retry budget is exhausted. The badge is computed from the delivery log, not stored in the endpoint record. If deliveries succeed again, the badge clears on its own without re-enabling.
Delivery status values (WebhookDelivery.status)
Section titled “Delivery status values (WebhookDelivery.status)”One row is written per attempt; retries each create a new row.
| Status | Meaning | responseStatus |
nextAttemptAt |
|---|---|---|---|
pending |
Queued; not yet sent | null |
set |
delivered |
Endpoint returned 2xx |
the HTTP status | null |
failed |
Endpoint returned non-2xx and a retry is pending | the HTTP status | set (next retry time) |
dead |
Retry budget exhausted (attempt 6 of 6 returned non-2xx) — terminal | last HTTP status | null |
When the last delivery for an endpoint reaches dead, the endpoint’s stored status flips to dead as well.
Retry schedule
Section titled “Retry schedule”MapleGather retries failed deliveries up to 6 attempts total over approximately 24 hours using exponential backoff. Return any 2xx to acknowledge receipt; any other status 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.