NODAPI

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.

HeaderValor
X-NOD-Connection-IdId da conexão na NOD.
X-NOD-ProviderTipo da conexão: qrcode (não oficial) ou meta (oficial).
X-NOD-Event-IdId da entrega. Não muda entre tentativas: use para não processar duas vezes.
X-NOD-TimestampUnix em segundos, gerado a cada tentativa.
X-NOD-Signaturev1=<hex>. Na troca de segredo vêm duas, separadas por vírgula (v1=a,v1=b).

Como validar a assinatura (v1)

  1. Leia o corpo cru (bytes), antes de qualquer parse de JSON.
  2. Recuse se a diferença entre agora e X-NOD-Timestamp passar de 300 s.
  3. Calcule HMAC-SHA256(segredo, "v1:" + timestamp + ":" + eventId + ":" + corpo) em hexadecimal.
  4. Aceite se alguma v1= do header for igual, em tempo constante.
  5. 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):

CampoValor
segredosegredo-ficticio-de-assinatura
X-NOD-Timestamp1763300000
X-NOD-Event-Id0b9f6a1e-0000-4000-8000-000000000001
corpo{"EventType":"messages","n":12345678901234567890}
X-NOD-Signaturev1=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 Gone desliga 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.