What is a webhook?

A webhook is an automatic message that one service sends to an address you provide when an event happens, such as a payment succeeding. Instead of repeatedly asking “has anything changed?”, you are told when it does.

By Nazar Kashuba · Reviewed

With an ordinary API you ask and get an answer. With a webhook the other service calls you.

A simple example

A customer pays. The payment provider sends a message to your server’s webhook address saying “payment received for order 123”. Your server marks the order paid and sends the confirmation. You did not have to keep checking.

Why it is useful

  • Fast: you learn of events as they happen.
  • Efficient: no constant checking.
  • The standard way many services, including payment providers, report events.

How to handle them safely

  1. Verify the sender. Services sign webhook messages; check the signature so nobody can forge one.
  2. Reply quickly with a success status, and do heavy work afterwards.
  3. Expect duplicates and disorder. The same message can arrive twice or in an unexpected order; handling must be safe to repeat.
  4. Handle failures. Providers usually retry for a while; make sure that works for you, and keep a way to reconcile missed events.
  5. Log them, so you can see what happened.

Webhooks are simple in idea and easy to get subtly wrong. The details of verification and repeat handling are where integrations usually go wrong.

Sources

All questions