Configurar webhooks

Objetivo

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

Procedimento recomendado

1. 11) Definir endpoint estável

   Usa o endpoint Beacon canónico sem redirects e com o org certo na query string.

2. 22) Guardar o signing secret

   Armazena o segredo no cofre de secrets e nunca em código.

3. 33) Validar eventos obrigatórios

   Confirma que a Stripe entrega os eventos mínimos esperados para checkout e subscrição.

4. 44) Configurar replay seguro

   Mantém replay manual por webhookEventId e registo de auditoria por evento.

Endpoints canónicos por ambiente

• Geral test: https://test.beacon.pt/api/webhooks/stripe?org=<organization_slug>&mode=test
• Geral live: https://app.beacon.pt/api/webhooks/stripe?org=<organization_slug>&mode=live
• Billing dedicado: mesma convenção em /api/webhooks/stripe/billing

Exemplo de verificação mínima

curl -X POST "https://test.beacon.pt/api/webhooks/stripe?org=acme&mode=test" \
-H "Content-Type: application/json" \
-H "Stripe-Signature: t=1710492000,v1=<assinatura_real>" \
-d '{"id":"evt_123","type":"checkout.session.completed"}'

Critérios de pronto

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