Webhook

A webhook is a reverse API call. With a normal API, your code calls someone else's server to ask for data. With a webhook, you flip the direction: you register a URL with the other system, and when an event you care about occurs, that system calls your URL.

The mechanics are plain HTTP. The source sends a POST request to your endpoint, usually with a JSON body describing the event, for example a payment that succeeded or a git push that landed. Your server reads the body, does whatever work the event requires, and returns a 200 status code to confirm receipt.

The word 'hook' means a place where you attach your own behavior. You are hooking your code into another system's event stream over the web, which is where the name comes from.

First you tell the provider where to send events. This is the subscription step: you give Stripe or GitHub a URL like https://yourapp.com/hooks/payments, and sometimes you also pick which event types you want.

When the event fires, the provider builds a payload and POSTs it to your URL. Most providers sign the request so you can verify it really came from them. Stripe puts an HMAC SHA-256 signature in a Stripe-Signature header; you recompute the signature using your shared secret and reject the request if it does not match. Skipping this check means anyone who knows your URL can forge events.

Your endpoint should reply fast, ideally under a few seconds, and do heavy work afterward. The common pattern is to write the payload to a queue or table, return 200 immediately, and process it in the background. If you return an error or time out, the provider retries, often with exponential backoff for hours. Those retries mean the same event can arrive twice, so you must handle them idempotently by tracking the event ID and ignoring duplicates.

Reach for webhooks when you need near real-time reactions to events that happen on someone else's system: a checkout completed, a CI build finished, a Slack message posted, a subscription renewed. They are far cheaper and faster than polling, because the provider does no work and your server does no work until something actually happens.

The cost is operational complexity on your side. Your endpoint must be publicly reachable, always up, fast, and secure. You have to verify signatures, deduplicate retries, and decide what to do when a webhook is missed entirely, since delivery is best-effort, not guaranteed. A good safety net is a periodic reconciliation job that pulls the full state from the provider's API to catch anything that slipped through.

Webhooks are also one-way and fire-and-forget from the sender's view. If you need a request and response in the same call, or guaranteed ordering and exactly-once delivery, a proper message queue or a streaming platform like Kafka is the better fit.

Say you run an online store and want to ship an order the instant payment clears. You register https://store.com/hooks/stripe with Stripe and subscribe to payment_intent.succeeded.

A customer pays. Stripe POSTs a JSON payload with the payment ID, amount, and customer details to your URL, along with a signature header. Your server verifies the signature, checks that it has not already processed that payment ID, enqueues a 'fulfill order' job, and returns 200 in under a second.

A background worker then picks up the job, marks the order paid, triggers the warehouse, and emails a receipt. The customer never waited for any of this, and your server never had to poll Stripe asking whether the payment went through.