Webhook: The Service Calls the Consumer

Objectives

By the end of the lesson, you can explain how a webhook works, distinguish it from polling and WebSocket, and list the tasks of the receiving side.

Why is it needed?

To learn about the events of an external service, polling (9.1) adds delay and load, and a persistent connection (chapter 10) means organisational overhead. The webhook reverses the direction: when the event occurs, the source calls a pre-registered address of the consumer.

What is a webhook?

A webhook is an HTTP call that the service (the source of the event) sends to the consumer's registered endpoint when an event occurs. The initiator is the provider; the consumer runs a receiving endpoint. It is not a persistent two-way channel and not a notification of the browser: it is an event-bound HTTP request between services.

sequenceDiagram
  participant F as Source service
  participant V as Receiving endpoint
  Note over F: Event occurs
  F->>V: POST (event + signature)
  V-->>F: 2xx (receipt)
  Note over V: Processing later

Tasks of the receiving side

The GitHub webhook guide shows the practical requirements well:

• Respond quickly with a 2xx (according to GitHub within 10 seconds, otherwise the delivery counts as failed), and do the actual processing in a background queue. A successful response therefore signals receipt, not complete business processing.
• Verify the sender. GitHub computes an HMAC signature (hash-based message authentication code, a keyed digest) of the payload and the shared secret with SHA-256, and sends it in the X-Hub-Signature-256 header; the receiver computes it itself from the raw, unmodified body and compares with a constant-time function. Re-serialising the payload can change the bytes; intermediate components can also break the verification.
• Handle duplication. GitHub sends a delivery identifier (X-GitHub-Delivery) by which a repetition can be recognised; a redelivery keeps the original value. The receiver therefore must be idempotent (6.5, 8.2).
• Missed events can be redelivered: according to the GitHub guide, redelivery is the receiver's job and option, not automatic.
• Use HTTPS and store the secret securely.

A timestamp and a limited acceptance window can protect against replay, but the window must be aligned with the provider's retry schedule.

Characteristics

Aspect	Webhook
Direction	One-way: source → receiver
Initiator	The source service
Connection persistence	One request per event
Latency	Quick after the event, but depends on the availability of the receiver
Load	Only per event; the receiver needs a public endpoint
Fault tolerance	Repetition, duplication, missed delivery; the receiver must be idempotent
When it fits	Occasional or moderate-frequency notification between services
When it does not	Updating a browser client; dense two-way message exchange; if the receiver is not reachable from outside

Webhook and its relatives

• Polling: the receiver asks; with a webhook the source sends, so there is no empty asking.
• WebSocket / SSE: a persistent channel with one client; the webhook is server-to-server and a new request per event.
• Message queue: the receiver need not be reachable at the time of sending; a webhook needs a reachable endpoint, and the receiver's availability depends on the sender's retry schedule.

Common misconceptions

Statement	Clarification
"A webhook is a notification of the browser."	A service calls the endpoint of another service.
"A webhook is WebSocket between servers."	A new HTTP request per event, not a persistent channel.
"It is trustworthy even without a signature."	The signature proves the sender.
"A 2xx response means the receiver processed it."	It signals receipt; processing can happen later.

In short

• A webhook is an HTTP call sent to the receiver's endpoint on an event; the initiator is the source.
• The receiver responds quickly, verifies the signature, deduplicates, and processes later.
• Redelivery is not automatic; idempotency is needed.
• Good for server-to-server notification, not for updating a browser.

Review questions

1. How does a webhook differ from polling and from WebSocket?
2. Why must the signature be verified on the raw body?
3. Why must the receiver of a webhook be idempotent?

Learning resources

• Validating webhook deliveries (GitHub Docs) — HMAC, raw body, constant-time comparison.
• Best practices for using webhooks (GitHub Docs) — fast response, background processing, deduplication.