Webhooks

Retries & dead letters

What happens when a delivery fails, and how to recover.

If your endpoint times out or returns a 5xx, the delivery is retried with exponential backoff. A 4xx is treated as permanent and the delivery is moved to the dead letter queue immediately.

Dead letters

Failed deliveries land in a queue you can inspect and replay. View them under Settings → Webhooks → Dead Letters in the dashboard, or:

Bash

GET /v1/webhooks/dead-letters
Authorization: Bearer hpn_live_sk_xxxxxxxxxxxxx

Param	Type	Description
`include_replayed`	boolean	Default `false`. Set to `true` to include already-replayed entries.
`limit`	integer	Default `100`, max `500`.

Replay a single delivery

Bash

POST /v1/webhooks/dead-letters/{id}/replay

Re-sends the original payload with a fresh signature and timestamp. The retry counter resets.

Replay in batch

Bash

POST /v1/webhooks/dead-letters/replay-batch
Content-Type: application/json

{
  "dead_letter_ids": [
    "550e8400-e29b-41d4-a716-446655440000",
    "650e8400-e29b-41d4-a716-446655440001"
  ]
}

Max 100 IDs per call.

The webhook_id in the replayed delivery is the same as the original, so your idempotent handler will treat it as a duplicate. If you want to re-process, drop your processed-id record first.

Endpoint management →

Idempotent handlers →