When your webhook endpoint misses events, backfill by reading messages with GET /v1/messages, which pages with before_id, and merge them into your records using a unique key. Do it on a schedule as well as after an outage, so a quiet failure doesn't go unnoticed for weeks.

Webhooks are fast but not guaranteed. A deploy, a bad certificate or a database stall can drop events, and providers retry for a limited time. A platform that trusts webhooks alone eventually has conversations with holes in them. Our post on webhooks versus polling explains why you want both, and dead-letter queues and replay covers events you did receive but couldn't process.

The backfill loop

  1. Pick a window. Note when the outage began and ended, and add padding at both ends.
  2. Page through messages. Call GET /v1/messages, then call again with before_id set to the last ID you got, until you pass the start of the window.
  3. Upsert each message into your store with a unique key on the message ID. A message you already have is a no-op.
  4. Reconcile statuses. A message you stored as sent may now be delivered or failed. Update it only if the new state is further along. See the message status state machine.
  5. Replay side effects once per new message: notify the rep, update the CRM, clear the unread badge.
def backfill(since):
    before_id = None
    while True:
        page = api.get("/v1/messages", params={"before_id": before_id} if before_id else {})
        if not page:
            break
        for m in page:
            if m_time(m) < since:
                return
            upsert_message(m)          # unique on message id: safe to repeat
        before_id = page[-1]["id"]

The field names above stand for the ones in the messages docs. Check them there before you copy the loop.

Make it safe to run twice

Backfill should be idempotent: running it again changes nothing. Use upserts, not inserts. Mark each side effect with a flag or an outbox row, so a replayed message doesn't notify a rep twice. See webhook deduplication and the transactional outbox pattern.

What polling can't recover

Lost thingRecoverable by polling?
Inbound repliesYes, they're messages
Delivery status changesUsually, by re-reading the message
Opt-outsRead GET /v1/opt-outs, and check one number with GET /v1/opt-outs/:phone
Your own app's reactionNo, you must replay it

Don't treat GET /v1/opt-outs as a full mirror. It lists only opted-out contacts on this account. Add ?scope=all for the account's whole Ban list, and check a single number before a send from another tool.

Schedule it

Run a small backfill every few minutes over the last hour. It's cheap, and it closes gaps you'd never otherwise see. Add an alert if the backfill finds more than a handful of messages your webhook missed, since that means the endpoint is unhealthy. See observability for SMS APIs.

Frequently asked questions

Does polling cost money? Reading messages isn't a send. Check the pricing page for what's billed.

How far back can I go? Page until you reach the start of your window, and no further than you need.

Should I drop webhooks and only poll? No. Webhooks give you speed, and polling gives you completeness.

Next step

Write the backfill as a function you can call with a start time, then run it against yesterday and check it adds nothing new.