Webhooks

What is a webhook?

A webhook is a way for one system to notify another in real time when an event happens, by sending an HTTP request (usually a POST with a JSON payload) to a URL you provide. It’s often called a “reverse API”: instead of you repeatedly calling a service to ask “anything new yet?”, the service calls you the moment there’s something to report. When a payment succeeds in Stripe, a push lands in GitHub, or a message arrives in Slack, a webhook fires an HTTP request to your endpoint carrying the event details. It’s the standard mechanism for event-driven integration between web services.

Webhooks vs polling — why they exist

The alternative to webhooks is polling: your system calls the other service on a schedule (“any new orders?”) over and over. Polling is simple but wasteful and laggy — poll too often and you hammer the API with mostly-empty responses (and hit rate limits); poll too rarely and you learn about events late. Webhooks invert this: the source pushes to you exactly when an event occurs, so you get near-real-time delivery with no wasted requests. That efficiency and immediacy is why virtually every SaaS platform offers webhooks for its events. The cost of the inversion is that webhooks make you run an always-available, publicly-reachable HTTP endpoint that must correctly and securely handle incoming requests — a webhook consumer has real responsibilities that a poller doesn’t.

The parts that bite: security and reliability

Two categories of problem trip up nearly everyone building webhook receivers. Security: your webhook URL is a public endpoint that anyone can send requests to, so you must verify that a request genuinely came from the expected sender — otherwise an attacker can forge events (fake “payment succeeded” notifications, for instance). The standard defense is signature verification: the provider signs each payload with a shared secret (an HMAC in a header), and you recompute and compare the signature before trusting the request. Skipping this is a serious, common vulnerability. You should also use HTTPS and, where possible, verify the source. Reliability: networks and servers fail, so webhook delivery is at-least-once, not exactly-once — providers retry on failure, which means your endpoint can receive the same event more than once, so handlers must be idempotent (processing a duplicate must not double-charge, double-ship, or double-send). Other reliability realities: respond quickly with a 2xx and do heavy work asynchronously (providers time out and retry slow endpoints, compounding load — the fix is to enqueue the event and return immediately); handle out-of-order delivery; and have a plan for missed events (many providers offer a replay or reconciliation API). The recurring mistakes are trusting unverified payloads, non-idempotent handlers that break on retries, and doing slow synchronous processing inside the webhook request.

What people get wrong

• Not verifying signatures — a public webhook URL accepts requests from anyone; without HMAC signature checks, attackers can forge events.
• Non-idempotent handlers: delivery is at-least-once, so the same event can arrive twice — handlers must safely tolerate duplicates or you’ll double-process.
• Slow synchronous processing — heavy work inside the request causes provider timeouts and retries; acknowledge fast (2xx) and process asynchronously via a queue.

Primary source: Stripe: webhooks guide