Webhook signing strategy
HMAC-SHA256 mandatory todos 6 inbound webhooks · timestamp replay protection <5min · idempotency keys mandatory · dual-key rotation window 24h zero downtime · 6 failure modes documented · 8-step rotation procedure transparent.
6 inbound webhooks · all signed
| Provider | Algoritmo | Secret | Validation |
|---|---|---|---|
| Meta WhatsApp Cloud API | HMAC-SHA256 con X-Hub-Signature-256 header | META_APP_SECRET · Cloudflare env · rotation trimestral | Constant-time comparison · entire body hashed · timestamp ≤5min · idempotent via message_id |
| Stripe | Stripe-Signature header con HMAC-SHA256 + timestamp | STRIPE_WEBHOOK_SECRET · per-endpoint · rotation post-incident only | stripe.webhooks.constructEvent() SDK · timestamp tolerance 5min · event.id idempotent |
| Cal.com | X-Cal-Signature-256 HMAC-SHA256 | CALCOM_WEBHOOK_SECRET · per-event-type · rotation trimestral | HMAC verification · timestamp check · payload.uid idempotent |
| QStash (Upstash) | Upstash-Signature header JWT · NextAuth verify | QSTASH_CURRENT_SIGNING_KEY + QSTASH_NEXT_SIGNING_KEY (dual) | JWT verification · dual-key window 24h rotation · job_id idempotent |
| GitHub Actions (CI webhooks) | X-Hub-Signature-256 HMAC-SHA256 | GITHUB_WEBHOOK_SECRET · rotation anual o post-secret-leak | Constant-time HMAC compare · timestamp X-GitHub-Delivery idempotent |
| UptimeRobot alerts | Shared secret token query param + IP whitelist Cloudflare | UPTIMEROBOT_WEBHOOK_TOKEN · query string · rotation trimestral | Token match + Cloudflare WAF IP whitelist UptimeRobot · alertContents idempotent via timestamp+monitorID |
Replay protection · 6 mechanisms
Failure modes · 6 escenarios
| Failure mode | Action taken |
|---|---|
| Invalid signature | Return HTTP 401 + log Sentry · NO process · alert si rate spike (potential attack) |
| Missing signature header | Return HTTP 400 + log · usually misconfigured provider integration · alert founder review |
| Timestamp expired (>5min) | Return HTTP 401 + log · could be legitimate clock skew o replay attack · investigate |
| Idempotency collision (already processed) | Return HTTP 200 (success idempotent) · log info-level · NO re-process · prevents double-charging style bugs |
| DB write failure post-validation | Return HTTP 5xx · provider auto-retries · idempotency key prevents duplicate side-effects on retry |
| Secret rotation in-progress (dual-key window) | Try CURRENT first · fallback NEXT · log which validated · transparent metric rotation progress |
Rotation procedure · 8-step zero-downtime
Dual-key window allows providers update sin coordination instant · zero failed webhooks durante rotation.
- T-0 · Rotation decision · ADR documented WHY (scheduled vs incident · secret leakage suspected)
- T+1h · Generate NEXT signing key · upload to Cloudflare env as `<PROVIDER>_WEBHOOK_SECRET_NEXT`
- T+2h · Configure provider dashboard (Meta · Stripe · etc) con NEXT key · provider starts using NEXT
- T+2h-24h · Dual-validation window · accept signatures from CURRENT or NEXT · monitor metrics which validated
- T+24h · Verify 100% traffic using NEXT key via metrics · if any traffic still CURRENT investigate misconfigured provider
- T+25h · Remove CURRENT key from Cloudflare env · promote NEXT to CURRENT · zero downtime achieved
- T+25h · Audit log rotation event · ADR updated · runbook /rotate-secret marks completion · postmortem si issues
- T+30d · Verify zero issues post-rotation · update encryption-key-management page con last-rotated date
Outbound webhooks (NOSOTROS hacia clientes) NO disponibles actualmente · roadmap post-tracción cuando clientes Enterprise lo soliciten para integrate sus CRM/EHR. Plan: same HMAC-SHA256 standard · signed con WEBHOOK_SECRET per-cliente · cliente verifies en su lado · idempotency keys provided.
Webhook retry policy: outbound futuro will follow Stripe-style exponential backoff (1m · 5m · 30m · 2h · 6h · 24h · max 72h total) · giving up logs event preserved DB para manual replay.
¿Tu engineering team necesita webhook integration details?
Para Enterprise procurement · code samples 4 idiomas verificación signatures · sample payloads · timing-attack hardened reference implementations disponibles bajo NDA.