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

Polling compared with a webhook With polling, your app keeps asking a service whether anything is new and mostly hears no. With a webhook, the service sends your app a message once, when something happens. Polling: your app keeps asking Your app Service Anything new? No, not yet (repeat) Webhook: the service tells you Your app Service Event happened sent once, straight away Verify the signature before you trust it
In words: With polling, your app repeatedly asks a service whether anything is new, and most replies are no. With a webhook, the service sends your app a message the moment an event happens, so there are fewer wasted requests and updates arrive sooner. Your app should check the message's signature before trusting it.

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

  1. 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.
  2. Publishing. When you publish a post, a webhook can trigger an automatic share to your social channels.
  3. Orders. A new shop order notifies the warehouse system to start fulfilment.
  4. 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.

  1. 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.
  2. Use the raw request body. Signatures are calculated on the exact bytes sent. If your framework parses the JSON first, verification can fail.
  3. Respond quickly. Return a success status (2xx) promptly and do slow work in the background. Slow or failing responses cause the provider to retry.
  4. 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.
  5. Keep secrets out of code. Store signing secrets in environment variables.
  6. 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.