Deliveries & Retries

A webhook that fires into a void is worse than no webhook: you believe the other system knows, and it does not. FerrisKey records every delivery attempt as a row you can query, with the HTTP status it got back, the error class when there was no status at all, and when it will try again.

The delivery record

GET /realms/{realm_name}/webhooks/{webhook_id}/deliveries
GET /realms/{realm_name}/webhooks/{webhook_id}/deliveries/{delivery_id}

The single-delivery read wraps the same summary alongside the payload that was sent, which is what you compare against what your endpoint logged:

{
  "data": {
    "summary": { "id": "…", "event": "user.created", "status": "failed", "attempt_count": 5, "last_status_code": 500 },
    "payload": { "…": "the body that was posted" }
  }
}

Status, and what it means for you

Error codes

When there is no HTTP response to report, the delivery carries one of ten error codes. They separate the causes that need different fixes:

Automatic retries

A failed delivery is retried with exponential backoff and jitter. Four numbers govern it:

base_delay_ms is the wait before the first retry; each subsequent wait grows and is capped by max_delay_ms. max_total_delay_ms caps the whole sequence, so a delivery stops being retried when either the attempt count or the total elapsed budget runs out — whichever comes first.

Jitter is applied to each interval, which is what stops a hundred deliveries that failed together from retrying in lockstep and hammering your endpoint the moment it comes back.

Where the numbers come from

The policy resolves in three layers, each field independently:

1. The webhook’s own retry_policy, when it sets that field.
2. Otherwise the realm’s setting — webhook_retry_max_attempts, webhook_retry_base_delay_ms, webhook_retry_max_delay_ms, webhook_retry_max_total_delay_ms.
3. Otherwise the system default above.

Because the resolution is per field, a webhook can raise only max_attempts and inherit the three delays. A webhook read returns both retry_policy (what this webhook overrides) and effective_retry_policy (what will actually be applied) — use the second one when you want to know what the worker will do.

When the attempts run out

The delivery goes failed, and SeaWatch records webhook_delivery_exhausted. That event is the one to alert on: it is the difference between “a delivery failed and recovered” and “this endpoint has been unreachable long enough that we gave up”.

Manual replay

POST /realms/{realm_name}/webhooks/{webhook_id}/deliveries/{delivery_id}/retry

Puts a terminal delivery back in the queue so the worker attempts it again. This is the tool for the ordinary case: the receiving service was down for an hour, the deliveries exhausted their attempts, the service is back and you want the events it missed.

Replay re-sends the stored payload, unchanged. It is not a fresh snapshot of the resource — the event described the world as it was, and replaying it says the same thing again. If the resource has since changed twice more, your endpoint will also receive those deliveries, and the order it sees them in is the order they are replayed.

Rotating the signing secret

POST /realms/{realm_name}/webhooks/{webhook_id}/secret/rotate

Generates a new signing secret and returns it. This is the only response that ever contains the secret — it cannot be read back afterwards, so capture it from this call or rotate again.

Reading the console

The webhooks list summarises the state of every endpoint at a glance:

“Without event” above zero is almost always a mistake: a webhook was created and its triggers were never picked.

API reference

Required permissions: view_webhooks or manage_webhooks to read, manage_webhooks to create, update, delete, replay or rotate. manage_realm grants all of them. Note that query_webhooks exists as a permission but is not what the read endpoints accept.

Debugging a webhook that is not arriving