What Is a Webhook, and How Is It Different From an API?

Most explanations of "API vs webhook" understate how simple the actual distinction is: a typical API call is you asking a question and waiting for an answer — a request, then a response. A webhook flips that direction entirely — instead of you repeatedly asking "has anything changed yet?", the other system pushes a message to you the instant something actually happens. One is pull-based, initiated by the client; the other is push-based, initiated by the server the moment an event occurs.

How a typical API request works

A conventional API interaction is request-driven — your application sends a request to a specific endpoint, and the server responds, either immediately with the requested data or an error. If you want to know whether something has changed since your last request — a payment status, a new message, an order update — the only option with a plain request/response API is to ask again, repeatedly, a pattern called polling. Polling works, but it means making requests on a schedule regardless of whether anything has actually changed, which wastes both the client's and server's resources on empty checks.

How a webhook works instead

A webhook is a URL you register with another service, and instead of you polling that service for updates, the service sends an HTTP request — usually a POST with a JSON payload — directly to your registered URL the moment a specific event actually occurs. A payment gateway can notify your server the instant a payment succeeds or fails; a version control platform can notify a build system the instant code is pushed; a form service can notify your backend the instant someone submits a form. No polling, no wasted checks — the notification arrives exactly when the event happens, not on some fixed schedule.

The trade-offs of push vs pull

• Webhooks are far more efficient than polling for anything event-driven — no wasted requests checking for changes that haven't happened yet.
• Webhooks require your server to expose a publicly reachable URL that can receive incoming requests, which polling (a purely outbound pattern) doesn't need — this can complicate local development and requires basic security handling (like verifying a signature) to confirm a webhook actually came from the expected source.
• A webhook delivery can fail (your server was briefly down, a network blip) — reliable webhook systems handle this with retries, but your integration needs to account for the possibility of a missed or duplicate delivery, which a simple polling loop doesn't have to worry about in the same way.
• Polling is simpler to build and debug initially, since it's just a scheduled request rather than an incoming request your server has to be ready to receive at any time.

A concrete example: payment confirmation

Consider an online store waiting to know whether a customer's payment succeeded. Without webhooks, the store's server would need to repeatedly poll the payment gateway's API — "has this payment completed yet? has it completed yet?" — on some interval, wasting requests during the (often short) window before the payment actually resolves. With a webhook registered, the payment gateway instead sends a notification directly to the store's server the instant the payment succeeds or fails, and the store can update the order status immediately, without ever having needed to ask.

When you'd still use a regular API alongside webhooks

Webhooks are for being notified when something happens — they're not typically how you'd fetch a full, current snapshot of data on demand. A real integration commonly uses both: a webhook to get notified the moment an event occurs, and a regular API call to fetch full details about that event or to periodically reconcile your own records against the source of truth, in case a webhook delivery was ever missed. Treating a webhook as the only source of truth, with no periodic reconciliation via the regular API, is a common source of subtle data drift if a delivery is ever silently lost.

Common mistakes

• Trusting a webhook payload without verifying its signature, opening the door to spoofed requests from anyone who discovers the webhook URL.
• Assuming webhook delivery is guaranteed and never building any reconciliation via the regular API to catch a rare missed delivery.
• Not handling duplicate webhook deliveries — most webhook systems can occasionally send the same event twice, and an integration that isn't idempotent can process it twice as well.
• Confusing a webhook with a scheduled job — a webhook fires when an event happens, not on a fixed time interval; a cron job is the right tool for genuinely time-based triggers.

The short version: an API is something you ask; a webhook is something that tells you, unprompted, the moment an event happens. Webhooks eliminate the waste of polling for event-driven use cases, but they require a publicly reachable endpoint, signature verification for security, and some tolerance for occasional missed or duplicate deliveries — which is exactly why most real integrations pair webhooks with a regular API for reconciliation rather than relying on webhooks alone.