Treat SMS webhooks as hints that can arrive late, twice or out of order, and design your handler so the order doesn't matter. Give each message status a rank, only move a message forward, ignore anything that would move it backward, and reconcile against the API for anything you missed.
This post is for developers building a receiver for message status and inbound texts. We don't list event names or payload fields here, because those belong in the docs. Check the API quickstart and the messages reference for the real shapes, and use the ideas below with them.
Why order isn't guaranteed
Webhooks are HTTP requests sent by a provider's workers, and several things reorder them.
- Retries. If your endpoint was slow or returned an error, the provider sends the event again later. A retry of an older event can land after a newer one.
- Parallel delivery. Events for one message can go out on different workers and take different network paths.
- Upstream timing. Carriers report on their own schedule, and status information can reach the provider in the wrong order.
- Your own infrastructure. A load balancer sends two requests to two pods, and the slower one finishes last.
None of this is a defect. It's how queued HTTP delivery works across any provider. The fix belongs in your handler.
A concrete failure
Take one text. In order, it's accepted, sent, then delivered. Suppose the "delivered" update reaches you first, and the "sent" update arrives a moment after. A naive handler that writes the latest event it saw sets the message back to "sent". Now your product shows a delivered text as merely sent, and a follow-up job that waits for delivery never fires.
Our post on delivery reports explains why a send response isn't a delivery result. This post covers what to do when the results themselves come in the wrong order.
Rank states instead of trusting arrival order
Define the statuses your product cares about and give each a rank. The shape, in general terms:
| Kind of state | Rank | Can it be replaced? |
|---|---|---|
| Queued or accepted | Lowest | Yes, by anything later |
| In flight or sent | Middle | Yes, by a final state |
| Delivered | Final | Not by an earlier state |
| Failed or undelivered | Final | Not by an earlier state |
Your own table of statuses will follow whatever the docs list. The rule is the same: an update applies only if its rank is higher than the stored one. A late "sent" can't overwrite "delivered", because "sent" ranks lower.
Make the write itself conditional, in one statement, rather than reading then writing. In SQL that means an update whose WHERE clause includes the current rank being lower than the new rank. A read-then-write has a race window, and two concurrent handlers will find it.
Final states can disagree with each other. A text marked failed that later reports delivered is rare but possible. Decide your policy and log the conflict. Don't silently pick whichever arrived last.
Use timestamps carefully
If an event carries a time, store it as the event's time, separate from your receive time. It helps in two ways: you can show the real timeline, and you can break ties between events of the same rank.
Don't build ordering on timestamps alone. Clocks differ between systems, and two events can share a second. Rank decides the direction, and the timestamp is supporting evidence. Never reject an event just because its timestamp is old, since a legitimate retry is old by definition.
Deduplicate before you act
The same event can be delivered more than once. Ready sends an X-Ready-Event-Id header that stays the same on every retry, so store that as a unique key per event with a unique constraint. If you also want to dedupe on content, the message id plus the status works too. Insert it first. If the insert fails because the key exists, you've seen it, so return success and do nothing more.
Return a 2xx quickly. Do the minimum in the request: verify the signature, record the event and enqueue the work, then respond. Slow handlers cause retries, and retries cause the reordering you're guarding against. Verify the signature over the raw body first, as in authentication and webhook signing.
Inbound texts and conversation order
Inbound messages have the same problem on a different axis. Two replies from a contact can arrive in your handler in swapped order, which turns a conversation into nonsense.
Order a thread by the message's own time when one is provided, and use your receive order only as a tiebreaker. Store each inbound message under its provider id with a unique constraint so a retry doesn't create a duplicate row. Our guide to inbound webhooks covers queues and reconciliation, and the conversation data model post covers how to store threads.
Opt-outs deserve extra care. If a STOP and a later text arrive swapped, you must not act as if the opt-out never happened. Ready honors inbound STOP and blocks the number, but your own systems should treat any opt-out as sticky: once recorded, only a fresh, documented opt-in can lift it. Before a send from another tool, check GET /v1/opt-outs/:phone.
Reconcile on a schedule
Even a perfect handler can't process an event that never arrived. Run a job that reads recent messages with GET /v1/messages (it pages with before_id) and compares each message's status with what you stored. Where the API is ahead of you, update your record using the same rank rule. Where a message is stuck in a middle state for longer than you'd expect, flag it.
This turns "we trust webhooks" into "we use webhooks for speed and the API for truth". The webhook gives you a fast update. The read-back gives you a guarantee. A short window, such as the last day of messages, is enough for most products, and a wider sweep can run less often.
A handler outline
In plain steps:
- Verify the signature over the raw body. Reject on failure.
- Parse the event and build its unique key.
- Insert the key. If it exists, return 2xx and stop.
- Enqueue the work and return 2xx.
- In the worker, apply a conditional update: set the status only if the new rank is higher.
- Record the event's own time alongside the status, as supporting evidence.
- Log any event that was ignored for being lower rank, with the message id.
Step 7 is how you notice a pattern. A steady trickle of ignored events is normal. A sudden flood suggests an upstream delay or a slow receiver, and the alerts in our observability guide are the place to catch it.
Test the ugly cases
Your tests should replay events in the wrong order on purpose. Send final before middle. Send the same event five times. Send an old retry after a newer state. Run two copies of the handler on the same message at once. If the stored status is the same every time, your design holds.
Build these as fixtures with made-up message ids and numbers, never real contacts. Our sandbox guide covers testing without real sends.
The short version
Don't trust arrival order. Rank statuses, update conditionally, deduplicate with a unique key, answer fast, and reconcile against the API. To start building, sign up and work through the API quickstart, including its webhook step.