Services

Resources

Company

/

Webhook

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:

import hashlib, hmac

def verify(secret: bytes, body: bytes, header: str) -> bool:
    # header is X-Hub-Signature-256, e.g. "sha256=5257a8..."
    expected = "sha256=" + hmac.new(secret, body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header)
import hashlib, hmac

def verify(secret: bytes, body: bytes, header: str) -> bool:
    # header is X-Hub-Signature-256, e.g. "sha256=5257a8..."
    expected = "sha256=" + hmac.new(secret, body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header)
import hashlib, hmac

def verify(secret: bytes, body: bytes, header: str) -> bool:
    # header is X-Hub-Signature-256, e.g. "sha256=5257a8..."
    expected = "sha256=" + hmac.new(secret, body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header)
import hashlib, hmac

def verify(secret: bytes, body: bytes, header: str) -> bool:
    # header is X-Hub-Signature-256, e.g. "sha256=5257a8..."
    expected = "sha256=" + hmac.new(secret, body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header)
import hashlib, hmac

def verify(secret: bytes, body: bytes, header: str) -> bool:
    # header is X-Hub-Signature-256, e.g. "sha256=5257a8..."
    expected = "sha256=" + hmac.new(secret, body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header)

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

  1. GitHub Docs: Validating webhook deliveries

  2. Stripe Docs: Receive Stripe events in your webhook endpoint

Sequence diagram of a payment webhook between the provider, your handler and an invoicing API. The provider POSTs a payment to the handler, which asks the invoicing API to create an invoice; that call takes 12 seconds. The provider times out after 10 seconds and retries 3 times, and each retry creates another invoice: 1 payment, 4 invoices. In red: 3,000 payments x 4 = 12,000 invoices.