Fallos de webhooks

Síntoma A: El endpoint del webhook devuelve 4xx/5xx

Cómo verificar: Panel → Propiedad → Webhooks → Registro de entregas — muestra códigos de estado y cuerpos de respuesta.

Causas y soluciones:

Código de estado	Causa probable	Solución
`401`	Fallo en la verificación de firma	Compruebe su código de verificación — consulte Seguridad de webhooks
`400`	Su endpoint rechaza el formato del payload	Registre el cuerpo sin procesar y compruébelo con el esquema del payload
`404`	La URL del endpoint ha cambiado	Actualice la URL del webhook en Propiedad → Webhooks → [Webhook] → Editar
`500`	Error en su manejador de webhooks	Compruebe los registros de su servidor para el error
`timeout`	Su endpoint tarda demasiado en responder	Responda con `200` inmediatamente, procese de forma asíncrona

Causa: Las razones más comunes son:

Cadena de firma construida incorrectamente — debe ser {timestamp}.{raw_body} (no JSON analizado)
Usar un secreto diferente al que se muestra en el Panel
Leer un cuerpo almacenado en búfer/modificado en lugar de los bytes sin procesar

Solución: Asegúrese de leer el cuerpo de solicitud sin procesar antes de cualquier análisis JSON. En Express:

// DEBE usar middleware de cuerpo sin procesar
app.use('/webhooks', express.raw({ type: '*/*' }));

Causa: ConsentForge reintenta las entregas fallidas con retroceso exponencial — los retrasos son esperados después de los fallos iniciales.

Solución: Corrija el error subyacente (consulte el Síntoma A). Una vez que su endpoint devuelva 2xx, las entregas futuras serán inmediatas.

Cómo verificar: Compare el recuento del registro de entregas del Panel con el recuento recibido en su servidor.

Causa: Algunos eventos pueden haber agotado todos los reintentos (5 intentos en ~2 horas).

Solución: Propiedad → Webhooks → Registro de entregas → Filtrar: Fallidos — use el botón Reproducir para reenviar las entregas fallidas.