What are Webhooks?

The "do not call us, we will call you" pattern

Before webhooks, the way one system learned about events in another was polling — every minute, ask "anything new?" and process whatever came back. Polling wastes work when nothing has changed, misses events that come and go between polls, and scales badly when you have hundreds of accounts to check.

Webhooks flip the direction. You register a URL with the other system, and when something interesting happens it sends a JSON POST to that URL. Your code reacts immediately. The cost is that you now own a public endpoint that strangers can hit, and you have to do the work to make sure only the real sender can write to your data.

What real webhook code has to handle

A naive webhook handler is twenty lines. A correct one is two hundred. It has to verify the signature on every request to make sure the sender is who they claim to be. It has to be idempotent — the same event might arrive twice on retry, and your code cannot create a duplicate record. It needs to acknowledge fast (most senders time out in a few seconds) and process slow work asynchronously in a queue. It needs to log everything, because debugging webhooks after the fact without logs is impossible.

Why most webhook bugs are silent

Webhook bugs do not crash the page. They go missing. A misbehaving handler drops a "subscription cancelled" event and the customer keeps getting charged. A duplicate handler creates two invoices for one payment. A signature verification skip lets a malicious actor send forged events. These bugs do not surface until someone notices the numbers do not match — often weeks later, after a customer complaint. The fix is alerting on the gap between events you expected and events you processed, plus periodic reconciliation jobs against the source system.

Where you will run into webhooks

Every SaaS you integrate with — Stripe (charge succeeded, subscription canceled), GitHub (push, PR opened), Shopify (order created), Slack (message posted), Zoom (meeting ended). Modern products ship dozens of webhook event types as a primary integration surface alongside their REST API.

At QUANT LAB

Webhook integration is bread-and-butter work on our Stripe integration and API development engagements. Every webhook handler we ship includes signature verification, idempotency keys, a durable queue between receipt and processing, dead-letter logging for unrecoverable errors, and a replay mechanism for when something downstream broke. The Stripe webhook code running on our own production billing system has caught and gracefully handled every retry, duplicate, and out-of-order event Stripe has thrown at it for years.

Testing webhooks locally

Webhooks are hard to develop against because your local machine is not reachable from the public internet. Tools like Stripe CLI, ngrok, Cloudflare Tunnels, and the webhook tester built into many platforms forward live events to a localhost port for development. We require every webhook integration to ship with a documented replay mechanism so support engineers can re-feed a single event when something goes wrong — much cheaper than asking customers to recreate the conditions that produced the event.