Webhooks

HTTP como notificação, não como tela. Inbound: proveniência + ack rápido. Outbound: retries no worker (background-jobs). Contrato de erro/status: api-design. Authz da rota: authentication-authorization.

Inbound (eles → você)

1. Verifique assinatura (HMAC / chave do provedor) no raw body. Não parseie JSON antes se o provedor assina os bytes.
2. Rejeite timestamp velho (replay). Tolerância documentada (ex. 5 min).
3. Idempotência: event_id unique no Postgres. Duplicate → 200 sem reaplicar.
4. Responda 2xx rápido. Persist + background-jobs para o trabalho pesado. Timeout do provedor é curto.
5. Fail closed se a secret não estiver no env.

• Rota dedicada, HTTPS, secret por ambiente. Não a mesma key em staging/prod.
• Auth extra (mTLS, allowlist IP) só se o provedor e o repo já usarem — a assinatura é o mínimo.
• Não logue o payload cru (PII, tokens). Logue event_id, tipo, resultado.

Outbound (você → eles)