Webhook

A webhook is a user-defined HTTP callback: instead of a client repeatedly asking "has anything changed?", the provider sends an HTTP request to a URL the client registered whenever a relevant event occurs. Webhooks turn a pull model into a push model, delivering events in near real time and eliminating wasteful polling. They are the backbone of SaaS integrations — payment notifications, repository events, message delivery receipts.

How It Works

The consumer registers an endpoint URL and selects which events to receive. When such an event happens, the provider POSTs a payload (usually JSON) describing it to that URL. The consumer's endpoint processes the event and returns a 2xx quickly to acknowledge receipt; the provider treats non-2xx or timeouts as failures and retries with backoff.

Security is essential because the endpoint is publicly reachable. Providers sign payloads with an HMAC over the body using a shared secret, sent in a header; the consumer recomputes the signature to verify authenticity and integrity. Replay protection uses a timestamp in the signed payload. Because retries cause duplicates, payloads carry a unique event ID so consumers can dedupe — webhook delivery is at-least-once, not exactly-once.

When to Use It

Use webhooks when you need timely notification of events from an external system and control the receiving endpoint — Stripe payment events, GitHub push/PR events, CI/CD triggers, CRM updates. They are ideal when events are relatively infrequent and you want low latency without the cost of constant polling.

Trade-offs

The consumer must run a publicly accessible, highly available endpoint; downtime means missed deliveries (mitigated by provider retries and a manual replay/backfill API). Delivery is at-least-once, so handlers must be idempotent. Local development needs tunneling tools to receive callbacks. Ordering is not guaranteed. Firewalls and strict networks may block inbound calls, where outbound polling or streaming fits better. Verifying signatures correctly is easy to get wrong and security-critical.

Related Patterns

Webhooks are the push alternative to polling and a lighter cousin of streaming for event delivery. They implement publish/subscribe across organizational boundaries. Idempotency keys/event IDs make duplicate deliveries safe, and the retry pattern governs redelivery on failure.

Example

POST /webhooks/stripe HTTP/1.1
Stripe-Signature: t=1719446400,v1=5257a869e7 d2...
Content-Type: application/json

{ "id": "evt_1NXa...", "type": "payment_intent.succeeded", "data": { ... } }

The consumer verifies the HMAC Stripe-Signature, checks it has not already processed event evt_1NXa..., handles it, and returns 200 OK so the provider stops retrying.