ADR-058 — Webhook security

Architecture decision record — status: Accepted.

Source: docs/adr/ADR-058-webhook-security.md

ADR-058: Webhook security

Estado

Accepted — 2026-08-23

Decisión

Webhooks inbound (Gmail push, Microsoft Graph, futuros Stripe):

  1. Path /api/v1/webhooks/:provider sin JWT de User.
  2. Verificar firma / token del vendor en el adapter antes del use case.
  3. Idempotencia por providerEventId (tabla o Redis). Replays = 200.
  4. Responder 2xx rápido; trabajo pesado (classify) vía outbox (ADR-022).
  5. No loguear el body crudo en INFO (ADR-028).
  6. Secrets de webhook en env (ADR-015), rotables.

Fallo de firma → 401/403, audit de seguridad, no crear Message.