Webhooks: recebedor seguro em Node.js

Baixe o recebedor executável. Ele valida a assinatura, recusa replays antigos e grava uma caixa de entrada SQLite antes de responder. Requer Node.js 24 ou superior, sem pacotes adicionais.

PrepararCopiar link

1. Configure NOVODID_WEBHOOK_SECRET em um cofre ou arquivo privado de ambiente. Use o segredo mostrado na criação do webhook, não o token da API.
2. Configure NOVODID_WEBHOOK_DB para um arquivo em volume privado persistente; o padrão é ./data/events.sqlite. PORT é 8787 por padrão.
3. Execute o arquivo com Node.js. Coloque um proxy HTTPS na frente e publique a rota /webhook.
4. Cadastre essa URL HTTPS em Desenvolvedores → Webhooks e escolha somente os eventos necessários. Localhost, redes privadas e redirects não são aceitos como destino da plataforma.
5. Use o teste do painel e confira as entregas. O recebedor responde 202 somente depois de persistir o evento.

O que o código validaCopiar link

• HMAC-SHA256 de timestamp + ponto + corpo bruto, comparado em tempo constante com X-Novodid-Signature.
• X-Novodid-Timestamp com diferença máxima de cinco minutos. Mantenha o relógio do servidor sincronizado.
• Corpo de até 256 KiB, versão v1 e tipo de evento conhecido.
• Duplicação pelo id do evento, não pelo identificador de cada tentativa. Um mesmo id com conteúdo diferente é recusado.

A tabela inbox guarda o JSON, tipo e estado pending. O exemplo recebe e persiste, mas não executa sua regra de negócio: implemente um trabalhador separado que processe linhas pendentes com idempotência. Só marque como processado após o sucesso da operação. Não suponha ordem nem entrega única.

Segurança e manutençãoCopiar link

O JSON pode conter dados pessoais e SMS: restrinja o volume, backups e acesso, e defina sua retenção. Não coloque o banco no git. Na rotação do segredo, atualize o ambiente do recebedor e reinicie o processo. Preserve o banco ao reiniciar. Não registre token, segredo, corpo completo ou assinatura em logs públicos.

401 indica assinatura/relógio incorretos; 413, corpo grande; 409, conflito de id; 503, falha de persistência. Confira Entregas no painel antes de reenviar. A plataforma tem prazo de oito segundos por entrega; o código confirma rapidamente após gravar, deixando trabalho pesado para o trabalhador. Para dados, eventos e política de repetição, consulte o guia da API.