API vs Webhook: The Difference Explained Simply

When two apps need to share information, developers usually reach for one of two tools: an API or a webhook. They're closely related and often work side by side, which is why the difference trips people up. If you run a business that relies on connected tools, knowing which is which makes conversations with developers and integration settings far less confusing.

Here's how I'd explain it, based on the official documentation from GitHub and Stripe, two services that offer both. The short version is that one asks and the other tells.

API vs webhook: pull versus push

With an API, your app pulls. It sends a request to another service whenever it wants something, and the service replies. If your app wants to know whether anything's changed, it has to keep asking. GitHub's documentation calls this polling: calling an API intermittently to see if data is available.

With a webhook, the other service pushes. You register a web address with it once, and when a chosen event happens, it sends an HTTP request with the event data to that address. GitHub describes webhooks as a way to subscribe to events and automatically receive a delivery of data to your server whenever those events occur. You only express interest in an event once, when you create the webhook.

A handy way to picture it: an API is you ringing the shop every hour to ask if your parcel's arrived. A webhook is the shop texting you the moment it does.

How an API request works between two apps

An API waits for a request. Your app sends one, often to a REST endpoint, and gets a response back with a status code and data, usually as JSON. If you'd like the full picture of endpoints, methods and status codes, I've covered them in what a REST API is.

Because your app controls the timing, APIs are good for on-demand jobs: looking up a record when a customer logs in, creating an order, or pulling a report when someone clicks a button.

How a webhook delivery works

A webhook turns the relationship round. The term was coined by Jeff Lindsay in 2007, and it's often described as a user-defined HTTP callback. Here's the usual flow:

1. You set up an endpoint on your server that can accept incoming requests.
2. You register that endpoint's address with the service and pick the events you care about.
3. When one of those events happens, the service sends a request, usually a POST with a JSON payload, to your endpoint.
4. Your endpoint checks the request really came from the service, replies quickly with a success code and then processes the data.

Stripe's guidance is clear on that last step: your endpoint must quickly return a successful status code in the 2xx range before any complex logic that could cause a timeout.

API and webhook compared side by side

	API	Webhook
Direction	Your app pulls data by asking	The service pushes data to you
Who starts it	Your app, whenever it chooses	The service, when an event happens
Timing	Only as fresh as your last request	Near real time
Setup	Call an endpoint with a key	Host an endpoint and register it
Good for	On-demand lookups and changes	Reacting to events as they happen
Watch out for	Hitting rate limits if you poll often	Fake requests, duplicates and retries

Everyday API and webhook examples

• Payment notifications. Stripe says receiving webhook events helps you respond to asynchronous events, such as when a customer's bank confirms a payment or a recurring payment succeeds.
• Form submissions. A form tool can push each new entry to your CRM or spreadsheet the moment it arrives, rather than your CRM checking for new entries.
• Chat apps. A team chat tool can receive a message when something happens elsewhere, such as a new support ticket.
• Code and deployments. Webhooks are widely used to trigger builds in continuous integration systems when code is pushed.
• On-demand lookups. When your app needs a customer's latest details at checkout, it calls the API and asks.

Webhook security: signing secrets and verification

Because a webhook endpoint is a public address, anyone could try sending it a fake request. Stripe warns that, without verification, an attacker could send fake events to trigger actions like fulfilling orders or granting account access. The standard protection is a signing secret:

• The service and your server share a secret. GitHub says to make it random and high-entropy, and never to hardcode it or push it to a repository.
• Each delivery carries a signature in a header. GitHub uses X-Hub-Signature-256, and Stripe uses Stripe-Signature. Both are HMAC signatures using SHA-256.
• Your server works out the expected signature from the raw request body and compares it using a constant-time comparison, which GitHub recommends to help mitigate timing attacks.
• Don't let your framework alter the raw body first, or verification will fail.
• Stripe also includes a timestamp so you can reject old requests, which helps prevent replay attacks.

Webhook reliability: retries, duplicates and order

Webhooks aren't fire and forget. Stripe says it retries failed deliveries for up to three days in live mode, that your endpoint might occasionally receive the same event more than once and that it doesn't guarantee events arrive in the order they were generated. So log the event IDs you've processed, skip ones you've seen and don't build logic that depends on a set order. If you miss something, you can use the API to fetch the latest state.

When to use an API, a webhook or both

GitHub's documentation sums it up well: webhooks need fewer resources than polling, scale better when you're watching lots of things and give near real-time updates. Calling the API still makes sense if you only need information once or now and then, or you're watching a small, fixed set of resources.

• Use an API when your app needs data on demand or needs to create, update or delete something.
• Use a webhook when you need to react to an event as soon as it happens.
• Use both for most real integrations: the webhook tells you something changed, and the API fetches the full, current details.

Learning more about APIs and webhooks

The webhook guides from GitHub and Stripe are some of the clearest free reading on the subject, and they're written for developers at every level. If you build integrations for a living, writing up what you've learned can help other people avoid the same pitfalls.

If integration guides are your speciality, see tech blogs covering APIs that take contributor pieces.

Frequently asked questions

Is a webhook a type of API?

It's closely related. A webhook is often described as a user-defined HTTP callback: instead of your app calling the service, the service calls your app's endpoint when an event happens.

Which is faster, an API or a webhook?

For news of an event, a webhook is usually quicker because it's sent when the event happens. With an API, you only find out when you next ask.

Do webhooks need a server?

Yes. You need an endpoint that's publicly reachable over the internet to receive the requests. Stripe requires live webhook endpoints to use HTTPS.

What happens if my webhook endpoint is down?

Many services retry. Stripe retries failed deliveries for up to three days in live mode, and you can use the API to catch up on anything you missed.

Can I stop polling if I use webhooks?

Mostly, yes. GitHub notes that webhooks avoid the repeated calls that can push you into rate limits, although an occasional API call can still be useful for catching up.