Falhas de Webhooks

Sintoma A: O endpoint do webhook devolve 4xx/5xx

Como verificar: Painel → Propriedade → Webhooks → Registo de Entregas — mostra códigos de estado e corpos de resposta.

Causas e correcções:

Código de estado	Causa provável	Correcção
401	Verificação de assinatura a falhar	Verifique o seu código de verificação — consulte Segurança de Webhooks
400	O seu endpoint rejeita o formato do payload	Registe o corpo bruto e compare com o esquema do payload
404	O URL do endpoint mudou	Actualize o URL do webhook em Propriedade → Webhooks → [Webhook] → Editar
500	Erro no seu handler de webhook	Verifique os registos do seu servidor para obter o erro
timeout	O seu endpoint demora demasiado a responder	Responda com 200 imediatamente, processe de forma assíncrona

---

Sintoma B: A verificação de assinatura do webhook está a falhar

Causa: Razões mais comuns:

1. Cadeia de assinatura construída incorrectamente — deve ser {timestamp}.{raw_body} (não JSON analisado)
2. Utilização de um segredo diferente do apresentado no Painel
3. Leitura de um corpo tamponado/modificado em vez dos bytes brutos

Correcção: Garanta que lê o corpo bruto do pedido antes de qualquer análise JSON. Em Express:

// DEVE utilizar middleware de corpo bruto
app.use('/webhooks', express.raw({ type: '*/*' }));

---

Sintoma C: As entregas de webhooks estão atrasadas

Causa: O ConsentForge tenta novamente as entregas falhadas com backoff exponencial — os atrasos são esperados após falhas iniciais.

Correcção: Corrija o erro subjacente (ver Sintoma A). Uma vez que o seu endpoint devolva 2xx, as entregas futuras serão imediatas.

---

Sintoma D: Entregas em falta — eventos não recebidos

Como verificar: Compare a contagem do registo de entregas do Painel com a contagem recebida no seu servidor.

Causa: Alguns eventos podem ter esgotado todas as tentativas (5 tentativas ao longo de ~2 horas).

Correcção: Propriedade → Webhooks → Registo de Entregas → Filtro: Falhadas — utilize o botão Repetir para reenviar as entregas falhadas.