Configurar webhooks
Configura endpoints webhook con validación de firma, reintentos y observabilidad.
howto • updated 2026-03-17
Objetivo
Garantizar que los eventos Stripe llegan a Beacon con validación criptográfica, deduplicación y replay seguro.
Procedimiento recomendado
11) Definir endpoint estable
Usa el endpoint canónico de Beacon sin redirects y con elorgcorrecto en la query.22) Guardar el signing secret
Guarda el secreto en el gestor de secretos, nunca en código.33) Validar eventos obligatorios
Confirma que Stripe envía los eventos mínimos de checkout y suscripción que Beacon espera.44) Configurar replay seguro
Mantén replay manual porwebhookEventIdy 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.