Webhooks & Callback APIs

Webhooks = HTTP callbacks

Callee (your SaaS) POSTs to subscriber URL when event occurs. Subscriber must:

1. Verify authenticity — HMAC signature over raw body (Stripe-Signature, X-Hub-Signature-256)
2. Respond quickly — 200 within timeout (often 5–30s); heavy work async
3. Handle duplicates — at-least-once delivery; dedupe by event_id
4. Tolerate downtime — sender retries with backoff; subscriber replays from dashboard

Signature verification pattern

expected = HMAC_SHA256(secret, timestamp + "." + raw_body) compare secure_equals(expected, header_signature) reject if timestamp too old (replay window)

Never parse JSON before verifying — whitespace changes hash.

Retry policy (sender side)

Typical: exponential backoff over hours/days, max N attempts, then mark failed + alert customer to fix URL.

Subscriber should return 410 Gone if endpoint permanently dead — sender stops retrying.

Ordering

No global order guarantee across event types. If order matters (created before paid), include sequence numbers or design idempotent state machine on resource_version.

vs polling

Webhooks: efficient, real-time, requires public endpoint (or tunnel in dev).

Polling: simpler security, worse latency/cost. ETag/cursor polling acceptable for low-frequency integrations.

Webhook delivery infrastructure

At scale, senders use delivery queues per subscriber, rate limits, circuit breakers when subscriber is down. Stripe/GitHub are reference implementations to study.

Standard Webhooks

Emerging spec for common headers (webhook-id, webhook-timestamp, webhook-signature) — reduces per-vendor integration code.

Security checklist

• HTTPS only
• Rotate secrets
• IP allowlist (weak alone; use signatures)
• Payload minimization (PII)
• Replay protection via timestamp