What is a webhook?

Webhook, explained#

Polling wastes effort on both sides: your code asks every minute whether anything changed, and almost always the answer is no. A webhook reverses the direction. You give the service an HTTPS endpoint and say which events you care about, and it calls you when one happens.

A delivery is normally a POST with a JSON body describing the event, plus headers naming the event type and carrying a signature. Your endpoint should check the signature, record the event, and answer 2xx quickly, doing any slow work afterwards. If it does not answer in time, or answers with an error, the sender retries, usually with growing delays.

Retries mean the same event can arrive more than once, so handlers should be idempotent: processing an event twice must have the same effect as processing it once. Store the event id, or make the action naturally repeatable. Events can also arrive out of order, so do not assume the second delivery describes the later change.

A webhook endpoint is a public URL that anyone can post to, which is why signatures matter. Without one, an attacker who finds the URL can send fake events. Senders, for their part, should refuse to deliver to private network addresses, so a webhook cannot be used to reach inside someone's infrastructure.

For example, finance wants to know the moment a deal is won. They point a webhook at their billing service. When a salesperson moves a deal to Won, the CRM posts deal.won with the deal's name and value, the billing service verifies the signature and drafts an invoice, and nobody had to copy anything across.