Skip to main content
Software Dictionary

Side by side

APIvsWebhook

What is the difference between an API and a webhook?

Updated 3 min read8 differences

In short

With an API, your app sends a request whenever it wants data; with a webhook, another service sends a request to your URL as soon as an event happens.

Backend & APIsp. 2

API

Application Programming Interface

An API is a set of rules that lets one piece of software request data or actions from another in a predictable, documented way.

Read the page on API
Backend & APIsp. 51

Webhook

A webhook is an automated HTTP request that one application sends to a URL you provide as soon as a specific event happens, such as a completed payment.

Read the page on Webhook

API and Webhook compared

AspectAPIWebhook
DirectionYour app calls the serviceThe service calls your app
TriggerYour code decides when to askAn event in the other system
TimingWhenever you ask; noticing changes needs pollingWithin seconds of the event
What you provideAn API key or token with each requestA public URL that accepts POST requests
DataWhatever you request: read, create, update or deleteA notification describing one event
Failure handlingYou see the error in the response and can retryThe sender retries; you must handle duplicates
SecurityThe service authenticates youYou verify the sender, usually by a signature
Typical useReading and changing data on demandPayment confirmations, Git pushes, form submissions

The difference, explained

An API is the set of operations a service offers: your application calls it whenever it needs something, such as reading an order or creating a payment, and gets a response right away. A webhook turns the direction around. You give a service a URL, and when an event you care about happens, such as a successful payment or a push to a repository, the service sends an HTTP POST to that URL with the details.

That is why webhooks are sometimes called reverse APIs. With an API alone, learning about changes means polling: asking again and again whether anything is new, which wastes requests and delays the news by up to the polling interval. A webhook delivers the event within seconds, and only when there is something to say.

They are partners more than alternatives. The URL you register for a webhook is in fact a small API endpoint of your own, which the other service calls, and most services offer both: webhooks to announce that something happened, and an API to fetch the full details or act on them. A typical handler receives a webhook, checks it, and then calls the sender's API for the latest state.

Webhooks bring their own duties. Because the URL is public, the receiver must verify each delivery, usually through a signature made with a shared secret. Senders retry failed deliveries, so the same event can arrive twice or out of order, and the handler should answer quickly with a 2xx status and do the real work in the background.

Which one should you use?

Choose API when…

  • Your app needs data or must take an action at a moment it chooses.
  • You need the full, current state of something, not just a notice that it changed.
  • Your app can't expose a public URL, such as a mobile app or a script behind a firewall.

Choose Webhook when…

  • You need to react quickly when something happens in another system.
  • Polling would waste requests or run into rate limits.
  • You can run a public, secured endpoint that handles retries and duplicates.

Polling an API vs receiving a webhook (Node.js)

APIjavascript
// API: your app asks, here every minute, whether the payment went through
setInterval(async () => {
  const res = await fetch(`https://api.pay.example/payments/${paymentId}`, {
    headers: { Authorization: `Bearer ${API_KEY}` },
  });
  const payment = await res.json();
  if (payment.status === "succeeded") markOrderAsPaid(payment.orderId);
}, 60_000);
Webhookjavascript
// Webhook: the provider calls your URL the moment the payment succeeds
app.post("/webhooks/payments", express.raw({ type: "application/json" }), (req, res) => {
  if (!isValidSignature(req)) return res.sendStatus(400); // shared-secret check

  const event = JSON.parse(req.body);
  if (event.type === "payment.succeeded") markOrderAsPaid(event.data.orderId);

  res.sendStatus(200); // answer quickly, or the sender will retry
});

Readers ask

Is a webhook an API?

In a sense. A webhook is an HTTP request one system sends to an endpoint of another, so the receiving URL is a tiny API. The difference is who starts the call: with a webhook, the provider does.

Webhook or polling: which is better?

Webhooks give timely updates with fewer requests; polling works when you can't receive incoming requests or need a simple fallback. Many integrations combine them, polling now and then to catch any missed webhook.

How do I secure a webhook endpoint?

Use HTTPS, verify the signature header with the shared secret, reject old timestamps to stop replays, and make the handler idempotent so a repeated event does no harm.

More

Settings

EnglishTürkçe