Webhook
With a webhook, the API calls you. Instead of asking GitHub every minute whether anyone pushed, you give GitHub a URL once. On every push, GitHub sends an HTTP POST to that URL with a JSON body describing the event. Payment providers do the same for payment_intent.succeeded, CI servers start builds this way, and Prometheus Alertmanager posts firing alerts to a webhook_config URL as JSON with an alerts array.
How it works
The receiver is an ordinary HTTP endpoint, often next to your REST API, but it is reachable from the internet and anyone can call it. So the sender signs each request. GitHub computes an HMAC, a SHA-256 hash keyed with a secret you both know, over the raw body and sends it in X-Hub-Signature-256. The receiver recomputes it and rejects anything that does not match:
Use a constant-time comparison like compare_digest, and hash the bytes exactly as received, before any JSON parsing.
Delivery is at least once. The sender waits a few seconds for a 2xx reply (GitHub allows 10) and treats a timeout or a 5xx as a failure. Stripe then retries with exponential backoff for up to three days. GitHub does not retry on its own; you redeliver from its UI or API. Either way the same event can arrive twice, so every event carries an ID to deduplicate on.
Here is how that goes wrong. A shop's handler creates an invoice inside the request, and the invoicing API takes 12 seconds. The provider times out at 10 seconds and retries up to 3 times, so each payment is delivered 4 times and every attempt runs to completion. A sale with 3,000 payments in an hour produces 3,000 x 4 = 12,000 invoices.
The fix has two parts. The handler checks the signature, stores the event ID with a unique constraint and returns 200 in about 50 ms. A worker then reads the stored events and creates one invoice per ID. That is idempotency applied to webhooks.
Why it matters in production
Webhooks are often the only way a third party can tell you something. When the endpoint breaks, your own dashboards may show nothing, because the failed calls never reached your code. In One2N's debugging story about failing webhook API requests, a third party's calls failed with a TLS error because the certificate in Nginx was valid for example.com but not for the webhook's subdomain. The developer's own curl test passed only because curl was set to always use --insecure.
Log every delivery with its event ID and status, alert on the provider's failure count, and park events your worker cannot process in a dead letter queue so a replay is possible.
See also
On the One2N blog
References
