A dead-letter queue (DLQ) for SMS webhooks is a holding area for events your system received but couldn't process, stored with enough detail to run them again later. Pair it with a replay tool and a reconciliation job and a bad deploy costs you minutes of delay instead of lost customer replies and missing opt-outs.
We make Ready, so Ready-specific details come from our docs. Webhook event names, payload fields and signature headers are listed in the docs quickstart, so we don't copy them here. The patterns below don't depend on field names.
Why SMS webhooks need this more than most
A missed webhook for a page view is a shrug. A missed inbound SMS can be a customer asking you to stop texting them, a reply to a sales lead or a verification answer. Three things go wrong in practice:
- Your handler throws. A bug, a full disk or a database outage means you return a 5xx, and the sender's retries run out.
- Your handler is down. A deploy, a certificate that expired or a misrouted DNS record means the event never arrives.
- Processing fails after the acknowledgement. You returned 2xx and then your worker crashed.
The third is the sneaky one, and it's why the design below stores the raw event before doing anything else. Our guide to receiving inbound webhooks covers acknowledge-fast, process-later; this post is what happens when "later" fails.
What to store
Save the event before you parse it, in a table like this:
| Column | Why |
|---|---|
id | Your own row ID |
received_at | Ordering and age alerts |
raw_body | The exact bytes, for replay and signature debugging |
provider_event_id | Unique constraint for deduplication |
status | pending, done, failed, parked |
attempts | How many times a worker tried |
last_error | The reason, so triage is fast |
The unique constraint on the provider's identifier makes redelivery harmless. If the same event arrives twice, the insert fails and you acknowledge anyway.
The worker and the parking rule
A worker pulls pending rows, processes each and marks it done. On failure, increment attempts, record the error and retry with backoff. After a limit, such as eight attempts over a few hours, set the row to parked and alert a human. Parked is your DLQ. Don't delete it and don't retry it forever.
Classify errors before you park:
- Transient (database timeout, downstream 503): retry with backoff.
- Permanent (unknown tenant, malformed payload): park right away. More retries won't help.
- Poison (an event that crashes the worker): park it and make sure it can't block the rows behind it.
Alert on the number of parked rows and on the age of the oldest pending one. Both belong on the dashboard described in observability for SMS APIs.
Replay safely
A replay tool re-runs parked or selected rows through the same worker code. Three rules keep it safe:
- Same code path. A separate "fix-up" script drifts from the real handler. Replay should enqueue rows back to
pending. - Idempotent side effects. Replaying an inbound reply that already created a CRM note must not create a second one. Key side effects on the provider event ID.
- Order awareness. Events can arrive out of order, and a replay makes that more likely. Our post on out-of-order SMS webhooks shows how to apply an event only if it's newer than current state.
Keep a "dry run" mode that lists what would be replayed and why. Use it before replaying hundreds of rows after an incident.
Reconcile against the source
A DLQ only catches events you received. For events that never arrived, reconcile. GET /v1/messages pages with before_id, so an hourly job can walk recent messages and insert any you don't have. Opt-outs have a matching read: GET /v1/opt-outs lists opted-out contacts on the account, and GET /v1/opt-outs/:phone checks one number. Ready also keeps a delivery log in the dashboard under Settings, Developers, Webhooks: every send of an event to your endpoint for 30 days, with a Resend button on a failed one. When your endpoint timed out or answered 5xx, 408 or 429, Ready keeps retrying on its own schedule (webhook delivery), so after a short outage those events arrive by themselves once the endpoint is back; any other 4xx is not retried, so resend those from the log. Run reconciliation after any incident and on a schedule. The message history sync guide shows the paging loop, and the delivery reports post covers status events.
Runbook for a missed-webhook incident
- Fix the cause and confirm the endpoint returns 2xx again.
- Replay parked rows with a dry run first.
- Run reconciliation for the outage window.
- Check opt-outs specifically, since a missed STOP is the one that carries legal weight.
- Write down how long events were delayed.
FAQ
Do I need a DLQ if my provider retries webhooks?
Yes. Provider retries stop after a while, and they can't help when your own worker fails after you've acknowledged the event. A DLQ is your side of the guarantee.
How long should I keep parked events?
Long enough to investigate and replay, often 14 to 30 days. Keep the raw body, and mind your privacy obligations, since message text is personal data.
Can I use SQS or a message broker instead of a database table?
Yes. A broker's built-in DLQ works well for the retry and parking steps. A table is easier to query and to build a replay tool on, so many teams use both.
The short version
Store the raw event first, dedupe on the provider's ID, park after limited retries, replay through the same code and reconcile against the messages API. For testing the endpoint before an incident, see testing webhooks locally.