Webhook

Protocol

Overview

A webhook is a 'reverse API' where, when an event occurs, a server sends an HTTP request (usually POST) to a pre-registered URL to proactively notify the other party.

Opposite to polling — where the client keeps asking — the server tells you only when an event happens, often described as 'don't call us, we'll call you.'

Details

How it works: the receiver registers a public endpoint URL with the provider, and when an event fires — payment completed, deploy succeeded, new message — the provider POSTs the event data to that URL. Versus polling it's more real-time and efficient, eliminating wasted requests. Most SaaS platforms (GitHub, Stripe, Slack) notify events this way.

Webhooks bring distinct reliability and security challenges: (1) authentication: since the receiving URL is public, verify the request truly came from the provider using an HMAC signature (signing the payload with a shared secret); (2) retries and idempotency: if the receiver is down or times out, the provider retries, so the same event may arrive multiple times — dedupe by event ID and process idempotently; (3) respond fast: enqueue heavy work and return 2xx immediately to avoid retry storms and rate limits. As server-to-client real-time delivery it overlaps with SSE/WebSocket, but webhooks specialize in server-to-server event delivery.

Related types