Design Reliable Webhook Delivery

Plaid sits between thousands of banks and thousands of customer apps. When a bank posts new transactions on an Item, or a login breaks and needs re-auth, the customer needs to hear about it quickly so their app can react. Polling every Item constantly would be wasteful and slow, so Plaid pushes a webhook: an HTTP POST to a URL the customer registered ahead of time. The hard part is that the customer's endpoint is a system Plaid does not run. It can be slow, down for a deploy, misconfigured, or returning 500s for an hour. Delivery has to keep working through all of it. And a webhook that leaves Plaid has to arrive exactly the way it left.

Name what is and is not achievable up front. Exactly-once delivery over a network is impossible, because a lost response looks identical to a lost request and the sender can never tell them apart. So we aim for the reachable target instead. Plaid retries until it gets a 200, which gives at-least-once delivery, and the customer processes each event idempotently so a duplicate is harmless. There is a second lever unique to how Plaid built this, and it changes the whole risk profile: most Plaid webhooks carry no data. A SYNC_UPDATES_AVAILABLE event just says "this Item has changes, call sync." The transactions themselves come from a separate cursor-based sync call the customer makes next.

The Plaid angle

Plaid's webhooks are deliberately thin, and that design decision is the one to lead with. The SYNC_UPDATES_AVAILABLE webhook carries no transaction data, only "come and sync." Because the customer always re-syncs from their last saved cursor, a dropped webhook cannot cause permanent inconsistency: the next sync, triggered by a later webhook or a periodic poll, still catches every change. Say that early. It reframes the reliability bar. We still work hard to deliver every event, but the system is designed so that missing one is a delay, not data loss.