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
- Pick a window. Note when the outage began and ended, and add padding at both ends.
- Page through messages. Call
GET /v1/messages, then call again withbefore_idset to the last ID you got, until you pass the start of the window. - Upsert each message into your store with a unique key on the message ID. A message you already have is a no-op.
- 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.
- 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 thing | Recoverable by polling? |
|---|---|
| Inbound replies | Yes, they're messages |
| Delivery status changes | Usually, by re-reading the message |
| Opt-outs | Read GET /v1/opt-outs, and check one number with GET /v1/opt-outs/:phone |
| Your own app's reaction | No, 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.