Dead letters and recovery
What happens when the schedule is spent, and how to get the events back.
In short
- A delivery whose schedule is spent is kept, not dropped.
- A destination that fails 50 times in a row is disabled, and the fact is published as an event.
- Recovery resumes the destination and replays what died while it was down, in one call.
- If events were published but never attempted, gap repair re-queues them.
What lands in the dead-letter queue
Everything that ran out of attempts. The original event id is preserved, so a consumer that
dedupes on webhook-id will not double-process anything you replay.
curl https://api.hookget.com/v1/dlq -H "authorization: Bearer $HOOKGET_KEY"When a destination is disabled
Fifty consecutive failures, or one 410 Gone, takes a destination out of rotation.
HookGet then publishes hookget.endpoint.disabled as an ordinary event, so you can
subscribe to your own incidents.
That operational event reaches explicit subscribers only. A catch-all destination that is currently failing must not receive the news of its own failure — that is an amplifier, not a notification.
Getting the events back
| Situation | Call | What it does |
|---|---|---|
| Destination fixed | POST /v1/endpoints/{id}/recover | Clears the failure counter and replays that destination’s dead letters |
| Selected failures | POST /v1/dlq/replay | Re-queues dead letters, all or for one destination |
| One event | POST /v1/events/{id}/replay | Sends a single event again |
| Suspected gap | POST /v1/events/replay-missing | Finds events with no attempt at all and re-queues them; safe to run twice |
Gap repair exists because the queue is derived from storage rather than the other way round. If the queue is lost, the events are still there and can be re-derived — which is the practical reason to care which of the two is the source of truth.