Configurar webhooks

Configura endpoints webhook con validación de firma, reintentos y observabilidad.

howto • updated 2026-03-15

Objetivo

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

Procedimiento recomendado

11) Definir endpoint estable
Usa un endpoint HTTPS público dedicado a webhooks sin redirects.
22) Guardar el signing secret
Guarda el secreto en el gestor de secretos, nunca en código.
33) Implementar idempotencia
Procesa por event.id y descarta duplicados confirmados.
44) Configurar replay seguro
Mantén ventana de replay y trazabilidad por evento.

Ejemplo de validación de firma

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"}'

Criterios de listo

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