How do I backfill webhooks I missed?

List the sender's objects for the outage window from its API, skip every id you already received, and run the rest through the same idempotent handler your webhooks use. Before you do, check whether anything is still missing: a sender that got an error usually retries on its own schedule, so a short outage can heal itself. If a gateway stored the webhooks while your endpoint was down, there is nothing to fetch — replay the window instead.

Fill the gap

// Fill an outage gap: page through the sender's list API for objects created in the window, skip ids you already have.
// Missed creations only: an object created before the window, or one you already hold, is skipped even if it changed.
// fetchPage(cursor) -> { items: [{ id, created }], nextCursor } with nextCursor null on the last page
// alreadyReceived(id) -> boolean; handle(item) is the same idempotent handler your webhooks use
export async function backfillGap ({ fetchPage, alreadyReceived, handle, from, to }) {
  let cursor = null
  let filled = 0
  do {
    const { items, nextCursor } = await fetchPage(cursor)
    for (const item of items) {
      if (item.created < from || item.created >= to) continue
      if (await alreadyReceived(item.id)) continue
      await handle(item)
      filled++
    }
    cursor = nextCursor
  } while (cursor != null)
  return filled
}

Not the same as a history backfill

A history backfill loads everything from before your webhook subscription existed; that is How do I paginate through a webhook backfill?. This one fills in the objects created between two times when webhooks should have arrived and did not.

Missed creations, not missed updates

A list endpoint returns each object's current state, not every event that changed it, and this procedure keeps only the objects created during the outage that you never received. So it recovers new objects, in their current state. It does not recover a change to an object you already had: that object was created before the window, or its id is already in your store, so it is skipped even if it changed during the outage. To catch those, list the window by the sender's updated time and compare each object with your stored copy — see How do I verify webhook data is correct?.

When the webhooks were stored

If a gateway received the webhooks while your endpoint was down, nothing was lost: replay the outage window from the stored payloads, with no trip to the sender's API.

Related

• How do I replay webhooks after fixing a bug?
• How do I paginate through a webhook backfill?