Use webhooks as your main way to learn message status, and add a polling job on a schedule as the safety net. Webhooks are fast and cheap but can be missed, delayed or duplicated. Polling is slow and costs requests but gives you ground truth on your own schedule. Almost every platform that texts for its customers ends up running both.
The choice isn't really either/or. It's a question of which one is the primary path and which one is the repair path. This post walks through where each works, where each breaks, and a reconciliation job built on GET /v1/messages with before_id paging. For the shape of delivery reports themselves, read our guide to SMS webhook delivery reports first.
What each approach is good at
| Feature | Webhooks | Polling |
|---|---|---|
| Latency | Seconds, when it works | As slow as your interval |
| Request cost | One inbound request per event | Requests whether or not anything changed |
| Missed updates | Possible if your endpoint was down | Not possible, you ask for the state |
| Duplicates and order | Both can happen | Not an issue, you read current state |
| Needs a public URL | Yes | No |
| Works behind a firewall | Only with a tunnel | Yes |
| Good for | Live UI, triggering the next step | Backfill, audits, reports |
Read the table as a division of labor. Webhooks tell you quickly that something changed. Polling tells you reliably what is true.
When webhooks are the right primary path
Pick webhooks first when someone or something is waiting on the result. A customer watching a message thread, an automation that waits for a reply before continuing, a billing step that triggers on delivery. Polling for these would mean either a long interval and a stale screen, or a short interval and a lot of wasted calls.
Webhooks also scale with activity. A quiet account sends you nothing. A busy one sends a stream. You don't pay for empty checks.
The costs show up on your side:
- You need a public HTTPS endpoint that answers fast. Return a 2xx once the payload is stored, and do the real work in a background job.
- You must verify that the request is genuine. See authentication and webhook signing.
- You need to expect repeats and late arrivals. Our posts on out-of-order events and dead-letter queues and replay cover both.
The exact event names and payload fields are in the provider's docs. For Ready, start with the API quickstart.
When polling is the right primary path
Polling wins in a few honest cases. You're prototyping and don't want to expose an endpoint yet. You run a batch process, such as a nightly report, that has no live consumer. Your network can't accept inbound traffic. Or the volume is small enough that a check every minute is trivial.
Polling also has one structural advantage: it needs no state about what you missed. Each pass reads the current truth. That's why it makes a good repair path even when it's a poor primary one.
The failure mode is cost and lag. If you poll every message individually, the request count grows with your message count, and a status can be stale by a whole interval. Don't poll per message. Poll the list.
Why you need both
Webhook delivery from most providers is at least once. That means a report can arrive twice, and in rare cases not at all, for example while your endpoint is returning errors or being deployed. Every receiver that matters to money or to a customer's trust needs a way to find out what it missed.
A reconciliation job gives you that. It runs on a schedule, reads recent messages from the API, compares them with your database, and feeds any differences through the same update path your webhook handler uses. If you've modeled status as a state machine, as in our status state machine guide, the job is easy to write, because a repeated or stale update is simply refused by the transition rules.
The reconciliation job with before_id paging
GET /v1/messages returns your messages and pages with before_id. The pattern is cursor paging: ask for a page, take the ID of the last item, and pass it as before_id to get the next page. Keep going until you reach messages older than your cutoff, or until a page comes back empty.
A few design points, labelled as our assumptions:
- Look back a bounded window, for example the last 24 hours, not your whole history.
- Run it every 5 to 15 minutes for recent messages, and a wider sweep once a day.
- Only compare messages that are not yet in a terminal state in your database, plus any your database doesn't know about.
- Treat the API's current state as the source of truth and apply it through your normal transition function.
Check the messages docs for the real response shape and the ordering of results. The sketch below uses placeholder names, marked in the comments, so adapt them to what the docs show.
// Placeholder shape: replace with the fields the docs list for GET /v1/messages.
interface RemoteMessage {
id: string; // placeholder
status: string; // placeholder
created_at: string; // placeholder, ISO 8601
}
const BASE = "https://api.tryready.com";
async function fetchPage(beforeId?: string): Promise<RemoteMessage[]> {
const url = new URL("/v1/messages", BASE);
if (beforeId) url.searchParams.set("before_id", beforeId);
const res = await fetch(url, {
headers: { "X-API-Key": process.env.READY_API_KEY! },
signal: AbortSignal.timeout(10_000),
});
if (!res.ok) throw new Error(`list failed: ${res.status}`);
const data = await res.json();
// The response also carries next_before_id and has_more; the id of the last row works as the next before_id.
return data.data as RemoteMessage[];
}
export async function reconcile(
cutoff: Date,
applyStatus: (remote: RemoteMessage) => Promise<void>,
maxPages = 50,
) {
let beforeId: string | undefined;
for (let page = 0; page < maxPages; page++) {
const items = await fetchPage(beforeId);
if (items.length === 0) return;
for (const m of items) {
if (new Date(m.created_at) < cutoff) return; // past the window
await applyStatus(m); // same function the webhook handler calls
}
beforeId = items[items.length - 1].id;
}
} The maxPages guard stops a bug or an unexpected response from turning one job into an endless loop. The early return on the cutoff assumes newest-first ordering, so confirm that against the docs before you rely on it.
Handling what the job finds
The job should do more than overwrite. Treat the differences as signal:
- A message missing from your database. Something was sent outside your normal path, or your insert failed. Create the row and log it.
- A status your webhook handler never recorded. Apply it through the state machine and count it. A steady stream of these means your webhook endpoint is losing events.
- A status that disagrees with a terminal state. Don't overwrite it. Write it to a conflicts table for a person to review.
Export the count of repairs as a metric. If reconciliation fixes a handful of rows per day, the system is healthy. If it fixes hundreds, your webhook path has a problem worth finding. Our observability guide has more on what to alert on.
Keep polling polite
Even though it's a repair path, a poller can still hurt you. Add jitter to the schedule so every tenant's job doesn't fire on the same second. Back off on errors. Page with a modest size and a page cap. And if you run the job per sub-account, spread the work across the interval rather than looping through all of them at once. Our rate limits guide explains why bursts are the thing to avoid.
The short version
Webhooks for speed, polling for truth. Make webhooks the primary path when anything is waiting on a result. Run a reconciliation job that pages GET /v1/messages with before_id, looks back a bounded window, and applies what it finds through the same update function. Count the repairs, and let that number tell you whether your webhook path is healthy.
If you're deciding where to start, build the poller first. It's small, it works without a public URL, and it keeps working after you add webhooks on top.