Configurar webhooks

Configura endpoints de webhook com validação de assinatura, retries e observabilidade.

howto • updated 2026-03-15

Objetivo

Garantir que os eventos Stripe chegam ao Beacon com validação criptográfica, idempotência e capacidade de replay.

Procedimento recomendado

11) Definir endpoint estável
Usa um endpoint HTTPS público dedicado a webhooks sem redirects.
22) Guardar o signing secret
Armazena o segredo no cofre de secrets e nunca em código.
33) Implementar idempotência
Processa por event.id e ignora duplicados já confirmados.
44) Configurar replay seguro
Mantém janela de replay e registo de auditoria por evento.

Exemplo de verificação de assinatura

bash

curl -X POST https://api.beacon.pt/v1/webhooks/stripe \
-H "Content-Type: application/json" \
-H "Stripe-Signature: t=1710492000,v1=fake-signature" \
-d '{"id":"evt_123","type":"invoice.paid"}'

Critérios de pronto

Taxa de erro < 1% por janela de 15 minutos.
Reprocessamento de eventos possível por event.id.
Logs com correlação entre evento, organização e pipeline fiscal.