Falhas de webhooks
Sintoma A: Endpoint do webhook retorna 4xx/5xx
Como verificar: Painel → Propriedade → Webhooks → Registo de entrega — mostra códigos de estado e corpos de resposta.
Causas e soluções:
| Código de estado | Causa provável | Solução |
|---|---|---|
401 | Verificação de assinatura a falhar | Verifique o seu código de verificação — veja Segurança de webhooks |
400 | O seu endpoint rejeita o formato do payload | Registe o corpo bruto e verifique contra o esquema do payload |
404 | O URL do endpoint mudou | Atualize o URL do webhook em Propriedade → Webhooks → [Webhook] → Editar |
500 | Bug no seu handler de webhook | Verifique os logs do servidor para o erro |
timeout | O seu endpoint demora demasiado a responder | Responda com 200 imediatamente, processe de forma assíncrona |
Sintoma B: Verificação de assinatura do webhook a falhar
Causa: Razões mais comuns:
- String de assinatura construída incorretamente — deve ser
{timestamp}.{corpo_bruto}(não JSON analisado) - Usar um segredo diferente do mostrado no Painel
- Ler um corpo com buffer/modificado em vez dos bytes brutos
Solução: Certifique-se de que lê o corpo bruto do pedido antes de qualquer análise JSON. Em Express:
// DEVE usar 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 recuo exponencial — os atrasos são esperados após falhas iniciais.
Solução: Corrija o erro subjacente (veja Sintoma A). Depois de o seu endpoint retornar 2xx, as entregas futuras serão imediatas.
Sintoma D: Entregas em falta — eventos não recebidos
Como verificar: Compare a contagem do registo de entrega do Painel com a contagem recebida pelo seu servidor.
Causa: Alguns eventos podem ter esgotado todas as tentativas de repetição (5 tentativas em ~2 horas).
Solução: Propriedade → Webhooks → Registo de entrega → Filtrar: Falhados — use o botão Repetir para reenviar entregas falhadas.