HookSteadBETA

Webhook vs. API: what's the difference, and when to use each

An API answers when you ask; a webhook tells you when something happens. A side-by-side comparison with examples, and why most integrations use both.

5 min read · Updated

The short answer

An API is how you ask another system for something: "give me invoice 42", "create a customer". You send a request whenever you want, and it answers.

A webhook is how another system tells you something happened: "invoice 42 was just paid". It sends a request to a URL you gave it, at the moment of the event.

Put simply: with an API, you call them. With a webhook, they call you.

An everyday analogy

Waiting for a table at a busy restaurant, you can walk up to the host every five minutes and ask whether it's ready. That's polling an API. Or you take the buzzer, sit down, and it buzzes when your table is free. That's a webhook.

Side by side

APIWebhook
Who starts the requestYouThe provider
WhenWhenever you chooseWhen an event happens
DirectionYou → providerProvider → you
Who hosts the endpointThe providerYou
Typical useRead or change dataGet notified of changes
If nothing changesYou still spend requests askingNothing is sent
If your side is downYour request fails, you try againThe provider must retry, or the event is missed
AuthenticationYour API key in the requestThe provider's signature, checked by you

The same payment, both ways

With the API, your app asks Stripe about a payment:

bash
curl https://api.stripe.com/v1/payment_intents/pi_3Q… -u "sk_live_…:"

With a webhook, Stripe tells your app when the payment succeeds:

POST /webhooks/stripe HTTP/1.1
Stripe-Signature: t=1793952000,v1=5257a8…

{"type": "payment_intent.succeeded", "data": {"object": {"id": "pi_3Q…", "amount": 4900}}}

You didn't ask; Stripe sent it within seconds of the charge.

Is a webhook an API?

Sort of. A webhook is an HTTP request, and your webhook endpoint is a small API that the provider calls. That's why webhooks are sometimes called "reverse APIs" or "push APIs". The difference is who calls whom, and when.

You'll also see "webhook API" in providers' docs. That usually means the regular API you use to manage webhooks: create an endpoint, list event types, resend a delivery.

When to use which

Use a webhook when you need to react to something that happens elsewhere: a payment, a push to a repository, a new order, a form submission, a message in a chat. Polling for these wastes requests and adds delay.

Use the API when you need data on your schedule: loading a page, a nightly report, creating or changing something.

Use both, which is what most robust integrations do:

  1. The webhook tells you that something changed.
  2. Your handler calls the API to fetch the current state, which is always fresh even if events arrived late or out of order.
  3. A periodic job lists recent objects through the API, catching anything a webhook missed.

What webhooks add to your to-do list

Because the provider calls you, you take on jobs an API client never has:

HookStead takes most of that list off your plate: a stable URL for each provider, signatures verified on arrival, every event stored, and delivery to your app with retries and replay. Start with the docs.

Frequently asked questions

What is the difference between a webhook and an API?
With an API you send a request when you want data. With a webhook the provider sends a request to your URL when an event happens. API: you call them. Webhook: they call you.
Is a webhook push or pull?
Push. The provider pushes each event to you as it happens. Calling an API repeatedly to check for changes is pull (polling).
Do webhooks need an API key?
Not usually. Instead of you sending a key, the provider signs each request with a shared secret, and your endpoint checks the signature.
Is a webhook the same as a callback URL?
Mostly. A callback URL is any URL a system calls back. A webhook is a callback URL for events, usually configured once and called many times.