Guide

What Is a Webhook? A Practical Explanation

A webhook is an HTTP request that one system sends to another when something happens. Instead of asking repeatedly whether there is news, you give the other system a URL and it tells you.

The idea in one comparison

Suppose you want to know when a customer pays. With an API, your code asks the payment provider, "has this invoice been paid yet?" and keeps asking. That is polling: simple, but slow to notice changes and wasteful when nothing has changed.

With a webhook, you tell the provider once, "when an invoice is paid, send a request to this URL." The provider calls you within moments of the event. Your code does nothing until there is something to do.

Polling an APIWebhook
Who starts the requestYouThe provider
Delay before you knowUp to your polling intervalUsually seconds
Cost when nothing happensA request every intervalNone
What you must runA schedulerA public HTTPS endpoint
Failure modeYou miss nothing, just lateDeliveries can fail, repeat or arrive out of order

What a webhook request looks like

There is no special protocol. A webhook is an ordinary HTTP request, nearly always a POST with a JSON body:

A typical webhook delivery
POST /webhooks/payments HTTP/1.1
Host: api.example.com
Content-Type: application/json
User-Agent: Provider-Webhooks/1.0
X-Signature: sha256=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

{
  "id": "evt_8f3k2",
  "type": "invoice.paid",
  "created": 1794835200,
  "data": { "invoice": "inv_20391", "amount": 4900, "currency": "usd" }
}

Three parts matter. The event type says what happened. The payload carries the details. The signature header lets you prove the request really came from the provider.

What the receiver has to get right

  1. Verify the signature. Your endpoint is a public URL. Anyone can post to it. Check the signature before trusting a single field. See the security checklist.
  2. Answer quickly. Providers wait a few seconds at most. Acknowledge with a 2xx status, then do slow work in a background job.
  3. Expect duplicates. Providers retry when they are unsure a delivery worked, so the same event can arrive twice. See retries and idempotency.
  4. Do not depend on order. An "updated" event can overtake the "created" event it follows.

Seeing one for yourself

The fastest way to understand webhooks is to receive one. Create a URL here, paste it into any service that offers webhooks, trigger an event and read the request. You will see the exact headers and body that your own code will have to handle.

Related terms

  • Callback URL, notification URL, HTTP push: other names for the same idea.
  • Incoming webhook: a URL a service gives you so that you can post into it. Slack and Discord channel webhooks work this way.
  • Server-Sent Events and WebSockets: ways to hold a connection open and receive a stream. They suit clients that cannot expose a public URL, which is why webhook.stream offers its captured requests as a stream.