Beacon

Configurar webhooks

Ver como Markdown

Configurar webhooks

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

howto • updated 2026-03-17

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

bash
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.