The idea in one paragraph
A webhook is a message one system sends to another the moment something happens. Instead of your application asking “anything new?” every few minutes, the other service calls a web address you provide and tells you straight away. Think of the difference between refreshing your inbox and receiving a notification.
Polling versus webhooks
| Polling | Webhooks | |
|---|---|---|
| Who starts the conversation? | Your app asks repeatedly | The other service pushes an event |
| Speed | Only as fast as your interval | Near real time |
| Wasted requests | Many, most return nothing new | Few, only when something happens |
| Complexity | Simple to start | Needs a public endpoint and some care |
Polling compared with a webhook
Benefits
- Timely updates. You react when an event happens, not minutes later.
- Efficiency. Fewer pointless requests means less load on both sides.
- Flexibility. One event can trigger many actions, such as an email, a spreadsheet row and a chat message.
- Simple integration. All you need is a URL that accepts a web request.
Examples
- Payments. A payment provider such as Stripe calls your site when a payment succeeds or fails, so you can unlock access or send a receipt.
- Publishing. When you publish a post, a webhook can trigger an automatic share to your social channels.
- Orders. A new shop order notifies the warehouse system to start fulfilment.
- Team tools. A message in a chat tool creates a task in your project management app.
Using webhooks safely
My original post suggested that the callback URL itself made webhooks secure. That is not enough. Anyone who finds your URL can send it fake events, so a safe receiver should do the following.
- Verify the signature. Most providers sign each request, typically with an HMAC computed from a shared secret, and send it in a header (Stripe uses
Stripe-Signature). Check it before doing anything else. - Use the raw request body. Signatures are calculated on the exact bytes sent. If your framework parses the JSON first, verification can fail.
- Respond quickly. Return a success status (2xx) promptly and do slow work in the background. Slow or failing responses cause the provider to retry.
- Expect duplicates. Providers retry failed deliveries, so the same event may arrive more than once. Store event IDs and make your handler idempotent, which means processing an event twice has the same effect as once.
- Keep secrets out of code. Store signing secrets in environment variables.
- Use HTTPS only.
Testing
Most providers have a dashboard that lets you resend events, and tools exist to expose a local development server temporarily. Test failure cases as well as success: bad signatures, duplicates and slow responses.
Webhooks are one of the simplest ways to connect systems, and with a few safeguards they are reliable too.