Webhooks e assinatura
A NOD API envia os eventos da conexão para a URL que você cadastrar, assinados com um segredo só seu. Valide a assinatura antes de confiar no corpo.
Requisição
POST na sua URL (somente https), com Content-Type: application/json e User-Agent: NOD-Webhooks/1. A URL é gravada no painel ou em POST /webhook.
| Header | Valor |
|---|---|
X-NOD-Connection-Id | Id da conexão na NOD. |
X-NOD-Provider | Tipo da conexão: qrcode (não oficial) ou meta (oficial). |
X-NOD-Event-Id | Id da entrega. Não muda entre tentativas: use para não processar duas vezes. |
X-NOD-Timestamp | Unix em segundos, gerado a cada tentativa. |
X-NOD-Signature | v1=<hex>. Na troca de segredo vêm duas, separadas por vírgula (v1=a,v1=b). |
Como validar a assinatura (v1)
- Leia o corpo cru (bytes), antes de qualquer parse de JSON.
- Recuse se a diferença entre agora e
X-NOD-Timestamppassar de 300 s. - Calcule
HMAC-SHA256(segredo, "v1:" + timestamp + ":" + eventId + ":" + corpo)em hexadecimal. - Aceite se alguma
v1=do header for igual, em tempo constante. - Deduplique por
X-NOD-Event-Id(guarde os vistos por pelo menos 48 h).
O segredo aparece uma vez, ao criar a conexão. Para trocar, gere um novo no painel: o anterior continua assinando por 24 h, tempo de você atualizar o seu sistema.
Exemplo em Node.js
const crypto = require("node:crypto");
function verifyNod(req, secret, toleranceS = 300) {
const ts = req.get("X-NOD-Timestamp");
const eventId = req.get("X-NOD-Event-Id");
const header = req.get("X-NOD-Signature") || "";
if (!/^\d{1,12}$/.test(ts || "") || !eventId) return false;
if (Math.abs(Math.floor(Date.now() / 1000) - Number(ts)) > toleranceS) return false;
const expected = crypto
.createHmac("sha256", secret)
.update(`v1:${ts}:${eventId}:`)
.update(req.body) // Buffer cru
.digest();
return header.split(",").some((part) => {
const m = /^v1=([0-9a-f]{64})$/.exec(part.trim());
return m !== null && crypto.timingSafeEqual(Buffer.from(m[1], "hex"), expected);
});
}app.post("/nod-webhook", express.raw({ type: "*/*", limit: "5mb" }), (req, res) => {
if (!verifyNod(req, process.env.NOD_SIGNING_SECRET)) return res.sendStatus(401);
// deduplicar por req.get("X-NOD-Event-Id") e só então processar JSON.parse(req.body)
res.sendStatus(200);
});Vetor de teste
Confira o seu código com este caso fixo (o segredo é fictício; use uma tolerância grande, porque o timestamp é antigo):
| Campo | Valor |
|---|---|
| segredo | segredo-ficticio-de-assinatura |
| X-NOD-Timestamp | 1763300000 |
| X-NOD-Event-Id | 0b9f6a1e-0000-4000-8000-000000000001 |
| corpo | {"EventType":"messages","n":12345678901234567890} |
| X-NOD-Signature | v1=50c9c77fa3f98bd36154873b81dfc78d4a036bec4ad728cb2adc42e9891dd667 |
Respostas e novas tentativas
- Responda 2xx em até 10 s e processe depois, numa fila.
- Falhou? Novas tentativas após 30 s, 2 min, 10 min, 30 min, 2 h, 6 h e 12 h. Depois disso, a entrega para.
410 Gonedesliga o webhook da conexão (você religa no painel).- A mesma entrega pode chegar mais de uma vez, e a ordem entre entregas diferentes não é garantida.