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 API | Webhook | |
|---|---|---|
| Who starts the request | You | The provider |
| Delay before you know | Up to your polling interval | Usually seconds |
| Cost when nothing happens | A request every interval | None |
| What you must run | A scheduler | A public HTTPS endpoint |
| Failure mode | You miss nothing, just late | Deliveries 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:
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
- 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.
- Answer quickly. Providers wait a few seconds at most. Acknowledge with a 2xx status, then do slow work in a background job.
- Expect duplicates. Providers retry when they are unsure a delivery worked, so the same event can arrive twice. See retries and idempotency.
- 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.