Webhook

What it means

A webhook is an automatic notification one system sends another the moment something happens: an order arrives, a payment is confirmed, a shipment changes status. The receiving side exposes an address that processes the message.

It differs from an API in direction. We query an API when we need something; a webhook arrives by itself, without the system having to poll repeatedly.

A webhook usually carries not the whole record but only a message that something happened plus the ID of the order or payment. The receiving system fetches the details itself through the API, authenticated with an API key. That way nothing arriving from outside has to be trusted and the data are always read from the original source.

How it works in practice

In practice it is the cheapest way to link an online store, a payment gateway and the ledger almost in real time. The document is created when the event happens, not during a nightly transfer.

The design must assume a message may arrive twice or out of order. Processing is therefore idempotent - a repeated delivery of the same event must not create a second document. That belongs in the workflow description, not in a developer’s memory.

A payment gateway sends the e-shop a webhook that an order was paid and the order is marked as settled. The gateway, however, pays the money out in a lump sum net of fees. When booking we therefore compare the total of confirmed payments for the period with the payout on the bank statement, so the difference is only fees and not missing payments.

What to watch out for

The webhook address is public, so a signature or shared secret has to be verified - otherwise anyone can post a fake payment confirmation. And if the receiving system is down the message is lost: a good integration also reconciles for missing events.

To be safe, a developer writes the full body of every incoming webhook to the logs, customers’ names, addresses and phone numbers included. The logs are then kept for years and anyone with server access can read them. A technical convenience turns into uncontrolled processing of personal data, which the GDPR does not allow.