Configurar webhooks

Objetivo

Garantizar que los eventos Stripe llegan a Beacon con validación criptográfica, deduplicación y replay seguro.

Procedimiento recomendado

1. 11) Definir endpoint estable

   Usa el endpoint canónico de Beacon sin redirects y con el org correcto en la query.

2. 22) Guardar el signing secret

   Guarda el secreto en el gestor de secretos, nunca en código.

3. 33) Validar eventos obligatorios

   Confirma que Stripe envía los eventos mínimos de checkout y suscripción que Beacon espera.

4. 44) Configurar replay seguro

   Mantén replay manual por webhookEventId y trazabilidad por evento.

Endpoints canónicos por entorno

• General test: https://test.beacon.pt/api/webhooks/stripe?org=<organization_slug>&mode=test
• General live: https://app.beacon.pt/api/webhooks/stripe?org=<organization_slug>&mode=live
• Endpoint dedicado de billing: misma convención en /api/webhooks/stripe/billing

Ejemplo mínimo de validación

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=<firma_real>" \
-d '{"id":"evt_123","type":"checkout.session.completed"}'

Criterios de listo

• Tasa de error por debajo de 1% cada 15 minutos.
• Reprocesamiento disponible por webhookEventId.
• Logs con correlación entre evento, organización y pipeline fiscal.