Configure um receptor
Um administrador autorizado cadastra o webhook do projeto ou da organização. Use uma URL acessível pelo servidor e guarde o segredo retornado na criação. O cadastro pertence à API privada; uma API key pública não administra os webhooks.
O filtro eventTypes recebe nomes exatos de eventos separados por vírgula. Um filtro vazio assina todos os tipos. Confirme os tipos produzidos pela versão do backend do seu ambiente antes de restringir a assinatura.
Headers recebidos
A assinatura usa o segredo em UTF-8 e os bytes do corpo JSON enviado. Valide antes de fazer parse ou reserializar o JSON.
Valide em Node.js
rawBody deve ser o Buffer original recebido pelo servidor. Só depois de validar, faça JSON.parse(rawBody.toString('utf8')).
Processe com durabilidade
Verifique a assinatura, grave a entrega de forma durável e responda com 2xx. Use uma chave única com o webhook/receptor e X-Nexxo-Delivery para que uma repetição não execute o efeito duas vezes. Conclua o trabalho demorado em segundo plano.
O worker atual faz até dez tentativas para falhas comuns, com espera progressiva. Restrições de acesso podem adiar a entrega separadamente. O destino pode aceitar um POST e a resposta se perder; por isso a deduplicação continua necessária.
O payload vem do evento de domínio. Não assuma que ele é igual ao DTO HTTP de uma issue nem que todos os eventos têm os mesmos campos.