What Is a Webhook?

A webhook is one of the simplest and most powerful patterns in modern software — and also one of the most misunderstood. This guide explains exactly what a webhook is, how it works, and how to receive and debug one.

The one-sentence definition

A webhook is an automated HTTP request that one system sends to another the moment something happens. Instead of your application repeatedly asking a service "has anything changed yet?", the service simply calls a URL you gave it — pushing the data to you as soon as the event occurs.

People sometimes call webhooks "reverse APIs" or "HTTP callbacks." Both are accurate: with a normal API you make the request; with a webhook the provider makes the request to you.

A concrete example

Say you run an online store on Stripe. A customer pays. You want your app to know immediately so it can send a receipt and unlock the purchase.

• Without webhooks: your server would have to call the Stripe API every few seconds asking "any new payments?" — wasteful, slow, and rate-limited.
• With webhooks: you give Stripe a URL once. The instant a payment succeeds, Stripe sends an HTTP POST to that URL with the full payment details. Your app reacts in real time.

How a webhook works, step by step

1. You register a URL. In the provider's dashboard (Stripe, GitHub, Shopify, etc.) you enter an endpoint URL you control, like https://yourapp.com/webhooks/stripe.
2. An event happens. A payment completes, a pull request is opened, an order is created.
3. The provider sends an HTTP request. Usually a POST with a JSON body describing the event.
4. Your endpoint receives it and responds with a 2xx status code to acknowledge receipt.
5. If you don't respond (or respond with an error), the provider retries later — most providers retry for hours or days.

Anatomy of a webhook request

A webhook is just an HTTP request. It has four parts worth knowing:

• Method — almost always POST.
• Headers — content type, plus provider-specific headers like a signature (Stripe-Signature, X-Hub-Signature-256) and an event type.
• Body — the payload, usually JSON, describing what happened.
• A signature — a cryptographic hash that lets you verify the request genuinely came from the provider and wasn't forged.

Webhook vs API: the key difference

They are complementary, not competing. You typically use a provider's API to send requests and configure things, and webhooks to receive real-time notifications. We cover the trade-offs in depth in Webhooks vs Polling.

Why webhooks can be tricky

The concept is simple, but in practice webhooks introduce three real challenges:

• You need a public URL. The provider's servers must be able to reach your endpoint over the internet — which makes local development awkward.
• You can't see what's being sent until you've already written code to receive it. Debugging "why isn't my handler firing?" is hard when the payload is invisible.
• Delivery is at-least-once. Providers retry, so the same event can arrive more than once — your handler must be idempotent.

How to see a webhook before you write code

The fastest way to understand a webhook is to look at a real one. With a webhook tester you generate a temporary public URL, paste it into the provider's dashboard, fire a test event, and inspect the exact method, headers, and body that arrive — no receiver code required.

Next steps

• Webhooks vs Polling — which should you use?
• How to test webhooks locally
• How to verify webhook signatures
• Webhook best practices for reliable integrations