Webhooks vs APIs: The Difference, and What It Costs You

An API gives you data when you ask for it. A webhook sends you data the moment something happens, without being asked. You call an API; a webhook calls you. That is the whole difference in one line, and every other article will tell you the same thing.

What almost none of them tell you is what changes on your side of the wire once you switch. (If you want the mechanics of a webhook first, here is one exchange in full.) Calling an API is something your code does on its own schedule, and if it fails you retry. Receiving a webhook means running a public HTTP endpoint that a company you do not control will POST to at a moment you cannot predict, exactly once if you are lucky. The direction reverses, and with it the responsibility for reliability.

The one-sentence version, and why it is not enough

Here is the standard table everyone publishes, and it is correct as far as it goes:

Read the fourth row again, because it is the one that matters and the one usually left out. With an API, if your service is down, nothing happens; you simply call later. With a webhook, if your service is down when the event fires, the event was still sent. Whether you ever see it depends entirely on the provider’s retry policy, which is theirs, not yours, and varies wildly.

That is the actual trade. Not push versus pull. You are moving the availability requirement from them to you.

What you traded away when you stopped polling

Polling gets a bad reputation it only partly deserves. The case against it is real: to notice an event within a minute you have to ask every minute, forever, and almost every one of those calls returns nothing new. You burn rate limits, you burn CPU on both ends, and you still have up to a minute of lag.

Webhooks fix all of that. In exchange, you inherit five problems that polling never had:

Your endpoint is now public. Anyone who learns the URL can POST to it. A polling client has no attack surface at all; a webhook receiver has one on the open internet, which is why signature verification is not optional and why a valid signature still needs a timestamp check to stop replays.

Delivery is at-least-once, never exactly-once. If the provider sends an event and your acknowledgement is lost on the way back, it looks like a failure and gets sent again. You already did the work. Your handler now has to be idempotent or it will double-charge someone.

Order is not guaranteed. Stripe says this outright: creating a subscription can fire customer.subscription.created, invoice.created, and invoice.paid in whatever order they arrive. A handler that assumes created precedes updated will eventually act on a resource it thinks does not exist yet. Polling handed you the current state; webhooks hand you a sequence of state changes, and sequences can arrive shuffled.

You must answer fast. Most providers treat a slow response as a failed one. Do your real work inside the request handler, and one slow database query turns into a retry storm from a provider that thinks you are down.

Silence is ambiguous. With polling, no new data is a fact you confirmed. With webhooks, nothing arriving could mean nothing happened, or it could mean your endpoint has been quietly returning 500 for six hours and the provider gave up. You do not find out until someone asks why an order never shipped.

None of this makes webhooks a bad choice. It makes them a choice with a bill attached, and the bill is infrastructure.

The hybrid nobody explains: a webhook as a doorbell

Here is the pattern most mature integrations converge on, and it barely appears in any of the comparison articles: use both.

The webhook payload tells you that something happened and gives you an id. Your code then calls the API to fetch the current state of that object. The event is the trigger; the API is the source of truth.

1. webhook arrives:  { "type": "invoice.paid", "data": { "id": "in_1P9x..." } }
2. verify signature, return 200 immediately
3. queue a job
4. job calls GET /v1/invoices/in_1P9x...   <- current state, from the API
5. act on what the API returned

This solves the ordering problem outright. It does not matter whether invoice.paid overtakes invoice.created in flight, because you are not reconstructing state from the sequence of payloads. You are using each event as a hint that something is worth re-reading, then reading it.

It also sidesteps stale data. A webhook payload is a snapshot of the moment the event fired. If three updates happen in quick succession, the first webhook’s body is already outdated by the time your worker picks it up. The API always gives you now.

The cost is one extra round trip per event, and a dependency on the provider’s API being up when your worker runs. For payments and anything where acting on stale data means acting wrongly, that trade is almost always worth it. Some providers make this explicit: Stripe’s newer thin events carry little more than an id and expect you to fetch the rest.

Use the payload directly when the event is self-contained and low-stakes: a Slack message, a deploy notification, a cache invalidation. Fetch from the API when money, state machines, or anything a human will dispute is involved.

Where WebSockets fit

WebSockets come up in the same conversation and solve a genuinely different problem. A WebSocket is a persistent, bidirectional connection your client holds open. A webhook is a single HTTP request the server makes to you and then forgets about.

The practical split:

• WebSocket when the recipient is a browser or a mobile app, updates are frequent, and you need them within milliseconds. Live prices, chat, collaborative editing, a progress bar.
• Webhook when the recipient is a server, events are occasional, and you need durability more than speed. A payment cleared. A build finished. An order shipped.

A WebSocket that drops loses whatever was in flight unless you build replay on top. A webhook that fails can be retried and replayed from a queue, because each event is an independent request with its own lifecycle. That durability is the reason server-to-server integrations settled on webhooks rather than long-lived sockets.

So which one do you pick

Neither, usually. Real integrations use APIs for reading and writing, webhooks for knowing when to read, and polling as a backstop.

Pick the API alone when you control the timing and freshness is not critical: nightly syncs, reports, anything a user triggers by clicking a button. It is the simplest thing that works, and simple is undervalued.

Add webhooks when the delay of polling costs you something real, or when the event volume makes polling absurd. If you check every minute and something happens twice a day, you made 1,438 pointless requests. If a customer is staring at a spinner waiting for a payment to confirm, minutes of lag is a product problem, not an engineering preference.

Keep polling as a reconciliation job even after you add webhooks. This is the part experienced teams do and nobody writes down: a nightly sweep that asks the provider “what did I miss?” and repairs any gaps. Webhooks fail silently. A reconciliation pass is how you find out, and it takes an afternoon to write.

And be honest about the case for staying with polling. One provider, low volume, no payment data, and a cron job that runs every ten minutes is a perfectly good integration. You skip the public endpoint, the signature verification, the idempotency store, and the retry infrastructure entirely. That is not laziness; that is correctly sized engineering.

What the webhook side actually costs to run

If you do choose webhooks, this is the work that follows, and it is the same work in every project: verify signatures per provider, answer in milliseconds and process out of band, persist events before acknowledging, retry with backoff and jitter, break the circuit on a dead destination, catch exhausted retries in a dead letter queue, and keep a per-attempt history so you can answer “did event X arrive?” with evidence. None of it is research, all of it is yours to maintain, and if you would rather not, the gateways that do it for you differ more than their landing pages suggest.

That list is what a webhook gateway is, and whether to write it yourself is a real decision with real numbers on both sides, which we work through in build vs buy.

Webhooker exists to be that layer: an EU-hosted ingest URL per source that verifies the provider’s signature before accepting anything, stores the event durably, and delivers it to your service with retries and replay. Your handler stops being a public endpoint hardened against forgery and becomes an ordinary internal service consuming events that already passed the checks. You can point a provider at a verified ingest URL on the free plan, or read the docs first.

Frequently asked questions