Programming · concepts · web

What is a webhook?

You set up a payment, and your app reacts the instant the money clears. You push a commit, and a build starts on its own. Behind that immediacy is almost always a webhook. This guide explains, plainly, what a webhook is, how it differs from a normal API call, how to receive one safely, and where you have already been relying on them.

The short definition

A webhook is an automated HTTP request a service sends to a URL you control when an event happens. Rather than you asking a service for updates, the service notifies you the moment there is news.

That is why webhooks are often called a "reverse API". With a normal API you are the client: you make the request and the server answers. With a webhook the roles flip — the provider becomes the client and your endpoint is the server it calls.

Webhook vs polling an API

Before webhooks, the usual way to stay up to date was polling: call an API on a timer ("anything new yet?") over and over. Polling is simple but wasteful — most calls return nothing, and there is always a lag between the event and your next check.

• Polling — you ask repeatedly. Many wasted requests, delayed reaction, simple to build.
• Webhook — the service tells you once, immediately. Efficient and near real-time, but you must run an endpoint to receive it.

How a webhook works, step by step

1. You register a URL (your endpoint) with the provider and choose which events you care about.
2. When such an event happens, the provider sends an HTTP POST to your URL with a body (usually JSON) describing it.
3. Your server reads the payload, returns a quick 2xx status to acknowledge it, and does the real work afterwards.
4. If your endpoint is down or returns an error, most providers retry with backoff — which is why duplicates can happen.

A delivery looks much like any HTTP request:

POST /webhooks/payments  HTTP/1.1
Host: yourapp.com
X-Signature: t=1718600000,v1=9f86d08...

{ "event": "payment.succeeded", "id": "pay_42", "amount": 1999 }

Real examples you have already met

• Payments — Stripe and PayPal send a webhook when a charge succeeds, fails or is refunded, so your app updates the order without polling.
• Code hosting — GitHub and GitLab fire a webhook on push, pull request or issue, which is how CI builds and bots are triggered.
• Messaging — Slack, Discord and chat platforms use incoming webhooks to post messages and to notify your app of events.

Receiving one safely

A robust receiver does four things:

• Serve HTTPS and accept POST; reply with a fast 2xx, then process asynchronously.
• Verify the signature — providers sign the body (an HMAC with a shared secret). Reject anything that fails.
• Be idempotent — the same event may arrive more than once; use the event id so re-delivery is harmless.
• Return errors honestly — if you cannot process it, return a non-2xx so the provider retries instead of dropping it.

Webhooks need an always-on endpoint with a public HTTPS URL — which is why a small server or cloud instance is the usual home for a webhook receiver, rather than a machine that sleeps.

Frequently asked questions

What is a webhook in simple terms?

A webhook is an automated message a service sends to a URL you control the moment something happens — for example, "a payment succeeded" or "a new commit was pushed". Instead of you repeatedly asking a service "anything new yet?" (polling its API), the service calls you with an HTTP POST as soon as the event occurs. It is often described as a "reverse API": with a normal API you make the request; with a webhook the service makes the request to you.

What is the difference between a webhook and an API?

They are related but point in opposite directions. With a normal (REST) API you send a request to the provider when you want data, and they respond. With a webhook the provider sends a request to your server when an event happens, so you get data pushed to you in near real time without asking. A webhook is delivered over the same HTTP mechanics as an API — it is essentially the provider acting as the client and your endpoint acting as the server.

Why use a webhook instead of polling?

Polling means repeatedly calling an API on a timer to check for changes, which wastes requests and adds delay between the event and your reaction. Webhooks push the event to you the moment it happens, so they are more efficient and far closer to real time. The trade-off is that you must run an always-on endpoint to receive them, and handle retries and duplicate deliveries.

How do I receive a webhook securely?

Expose an HTTPS endpoint that accepts POST requests, return a 2xx status quickly to acknowledge receipt, and process the work asynchronously. Verify the payload signature the provider sends (an HMAC of the body with a shared secret) so you know the request is genuine, and make handling idempotent because providers may deliver the same event more than once. Reject anything that fails signature verification.

The bottom line

A webhook is the web's way of saying "don't call us, we'll call you": an automated HTTP request a service sends to your endpoint the instant an event happens. It is more efficient and far more real-time than polling an API — at the cost of running a reliable, signature-verifying endpoint to receive it. Once you see them, you will notice webhooks behind almost every "it just updated by itself" moment in modern software.