Webhook

What is a webhook?

A webhook is a user-defined HTTP endpoint that receives push notifications when something happens — a payment succeeds, a CI build finishes, a CRM contact updates. Instead of polling an API every minute, the source system POSTs JSON to your URL.

Flow

1. You register https://yourapp.com/hooks/stripe with a provider
2. Event occurs (e.g., invoice.paid)
3. Provider sends signed HTTP POST with event payload
4. Your handler validates signature, processes idempotently, returns 2xx

Webhooks vs polling

Approach	Pros	Cons
Polling	Simple to consume	Delayed, wasteful API calls
Webhooks	Real-time, efficient	Must expose public endpoint, handle retries

Reliability patterns

• Verify signatures (HMAC with shared secret)
• Respond quickly — queue heavy work asynchronously
• Idempotency — same event ID may be delivered more than once
• Retry handling — providers retry on non-2xx responses

Common sources

Stripe, GitHub, Slack, Shopify, Twilio, and most modern SaaS APIs expose webhooks. Serverless functions are a popular webhook target due to pay-per-use scaling.

Outbound vs inbound

Inbound webhooks — others call you. Outbound webhooks — your product notifies customer systems (common in B2B SaaS platforms).

What people get wrong

• Skipping signature verification. An unverified webhook endpoint is an open API that anyone can POST fake “payment succeeded” events to.
• Doing heavy work in the handler. Providers time out in seconds; acknowledge fast, queue the work, process async.
• Assuming exactly-once delivery. Every provider retries; without idempotency keys you will double-fulfill orders.
• No replay story. When your endpoint is down for an hour, how do you recover missed events? Most providers offer replay or event lists — wire it up before the outage.

Webhooks vs. Polling

Webhooks represent an inversion of the more traditional polling pattern, where a client repeatedly asks a server “has anything changed yet?” at fixed intervals — polling wastes resources on the vast majority of checks that find nothing new, and introduces a delay between when an event actually happens and when the next poll discovers it. Webhooks eliminate this waste and delay by having the source system push a notification immediately when an event occurs, rather than waiting to be asked. The tradeoff is that webhook receivers need to be publicly reachable (or reachable through some tunnel/relay mechanism) and must handle the operational realities of receiving external HTTP requests reliably — verifying request authenticity (typically via a signature included in the request), handling duplicate deliveries gracefully, and responding quickly enough that the sending system doesn’t consider the delivery failed and retry unnecessarily.