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
| API | Webhook | |
|---|---|---|
| Who starts the request | You | The provider |
| When | Whenever you choose | When an event happens |
| Direction | You → provider | Provider → you |
| Who hosts the endpoint | The provider | You |
| Typical use | Read or change data | Get notified of changes |
| If nothing changes | You still spend requests asking | Nothing is sent |
| If your side is down | Your request fails, you try again | The provider must retry, or the event is missed |
| Authentication | Your API key in the request | The provider's signature, checked by you |
The same payment, both ways
With the API, your app asks Stripe about a payment:
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:
- The webhook tells you that something changed.
- Your handler calls the API to fetch the current state, which is always fresh even if events arrived late or out of order.
- 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:
- A public URL that's up whenever events happen. See what a webhook URL is.
- Checking signatures, because anyone can call a public URL. See webhook signature verification.
- Handling duplicates and retries, because providers send again when they're unsure. See retries and idempotency.
- Testing without a public server. See webhook testing tools.
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.