API vs webhook: who calls whom, and why it matters

The short version#

An API (application programming interface) waits for you to ask a question and then answers it. A webhook is a message a system sends to you on its own, the moment something happens. With an API, your system makes the call. With a webhook, the other system makes the call. They aren’t rivals: a webhook is really a small, reversed API call, and most working integrations use both. The choice is about which direction the conversation starts from, and how fresh the data needs to be.

If you want the bigger picture first, our plain-English guide to API integration covers requests, responses and the common failure points. This page zooms in on one decision inside that picture.

Side by side#

The pizza analogy#

You’ve ordered a pizza. There are two ways to find out when it leaves the shop.

You can phone the shop every five minutes and ask, “Is it out yet?” That’s using an API by polling. It works, and you’re in control of when you ask. But most calls get “not yet,” the shop gets annoyed if you call too often, and if it left one minute after your last call, you won’t know for another four.

Or the shop can text you when the driver leaves. That’s a webhook. You don’t waste any calls, and you hear the news right away. But you have to give the shop a number that’s switched on, and if your phone is dead when the text arrives, you’re relying on the shop to try again.

Notice that even in the webhook version, you might still phone the shop afterwards to ask, “What toppings did I order again?” That’s the API again: the webhook tells you something happened, and the API lets you look up the details.

How the two fit together#

Here’s a common real arrangement, using a payment provider and an online store as the example.

1
  POLLING WITH AN API                  WEBHOOK, THEN API
2

3
 +-----------+   "anything new?"     +-----------+  "payment succeeded,
4
 |  Your     | --------------------> | Payment   |   id pi_123"
5
 |  store    | <-------------------- | provider  | ---------------+
6
 +-----------+   "no" (x 59)         +-----------+                |
7
       |         "yes, 1 new" (x 1)        ^                       v
8
       |                                   |                 +-----------+
9
       |  every minute, all day            |  GET /payments/ |  Your     |
10
       +-----------------------------------+  pi_123         |  store    |
11
                                           +---------------- | (receiver)|
12
                                              "details"      +-----------+

On the left, the store asks sixty times to learn one thing. On the right, the provider speaks once, and the store makes one follow-up request to fetch the full details. Many vendors deliberately keep webhook messages short and expect you to use the API for the rest.

What the documentation tells you to expect#

Webhooks come with promises and limits that vary by vendor, so it pays to read the fine print. Two examples from well-documented platforms:

• Retries. Stripe’s webhook documentation says it attempts to deliver events for up to three days in live mode, with exponential back-off (waiting a little longer between each attempt). That’s generous, but it means your system must cope with a message arriving late, or arriving more than once.
• Order. The same Stripe page says it doesn’t guarantee events arrive in the order they were generated. A “subscription updated” message could reach you before the “subscription created” one.
• Speed of reply. GitHub’s webhook best practices ask your server to respond with a success code within 10 seconds, or GitHub treats the delivery as failed. The usual pattern is to say “got it” immediately and do the slow work afterwards.
• Trust. Because anyone on the internet could send a message to your webhook address, vendors typically sign each message so the receiver can confirm it really came from them. Your developer or integration platform handles that check; the business point is simply to ask whether it’s in place.

None of this is a reason to avoid webhooks. It’s a reason to treat “we’ll just add a webhook” as a small project, not a checkbox.

Decision factors#

Run through these when someone asks which approach to use.

1. Does the business need to react within seconds or minutes? Payment confirmations, stock reservations and customer notifications usually do. Choose a webhook if the vendor offers one for that event.
2. Do you need history or bulk data? Last quarter’s invoices, a full customer list, a nightly reconciliation: use the API. Webhooks only describe what happens after you subscribe.
3. Does the vendor offer a webhook for this event at all? Check the event list in their documentation. If the event you need isn’t there, polling the API is your only option.
4. Can you host a receiver? A webhook needs an always-on address. If you use an automation platform, it usually provides one for you. If you’re building in-house, someone has to run and monitor it.
5. How many records change, and how often? Polling a system with thousands of records every minute can bump into rate limits (caps on how many requests you may make). Webhooks scale better for frequent small changes.
6. What happens if a message is missed? For anything financial, pair webhooks with a periodic API check that catches stragglers. Belt and braces is normal here.

A worked example: new sign-ups to your email tool#

Say your website form tool and your email marketing tool need to stay in step.

• Webhook route. The form tool sends a webhook to your automation platform each time someone submits. The platform adds the contact to the right list within seconds. The welcome email goes out while the person still has the tab open.
• API route. Every hour, the automation platform asks the form tool’s API, “Any new submissions since 2 p.m.?” and copies them across. Simpler to reason about, but the welcome email may land an hour later.
• Both. Use the webhook for speed, and run a nightly API job comparing the two lists to catch anything that slipped through while a system was down.

For a sales-led company, the hour’s delay might not matter. For a webinar sign-up that starts in ten minutes, it matters a lot.

What this means for a 20-person company

• When you evaluate a tool, look for an “events” or “webhooks” page in its documentation. If it’s missing, real-time automation with that tool will be harder.
• Automation platforms usually give you a webhook address without any server to run, which is often the easiest way to start.
• For money-related events, ask for a daily check that compares both systems, not just the webhook.
• Assign one person to watch failed-delivery alerts. Most vendors show a delivery log; someone should look at it weekly.

Also consider

• Polling with change filters. Many APIs let you ask only for “records changed since” a time stamp, which makes polling far cheaper.
• Streaming and message queues. Larger systems sometimes use a dedicated message service between apps instead of direct webhooks. That’s a middleware decision.
• An integration platform. If you’re stitching many tools together, an iPaaS platform (integration platform as a service) will receive webhooks, call APIs and retry failures for you.
• The vendor’s SDK. Some vendors ship code libraries that wrap both their API and their webhook checks. See API vs SDK for how those relate.