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`	Verificación de firma fallida	Verifique su código de verificación — consulte Seguridad de webhooks
`400`	Su endpoint rechaza el formato del payload	Registre el cuerpo sin procesar y compárelo con el esquema de 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	Revise los registros de su servidor para encontrar el error
`timeout`	Su endpoint tarda demasiado en responder	Responda con `200` inmediatamente, procese de forma asíncrona

Causa: Razones más comunes:

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 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 intentos de reintento (5 intentos en ~2 horas).

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