Enviar e receber

Webhooks

Tudo que chega de fora — mensagens recebidas, mudanças de estado de entrega, conexão de número — chega ao seu servidor por um webhook assinado. É o caminho principal; consultar a API é reconciliação.

1. Registrar o endpoint

POST /v1/webhooks

curl -X POST https://api.nuntis.com.br/v1/webhooks \
  -H "x-api-key: $NUNTIS_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "url": "https://api.seuproduto.com.br/hooks/nuntis",
    "events": ["message.received", "message.status"]
  }'

{
  "id": "wh_42",
  "url": "https://api.seuproduto.com.br/hooks/nuntis",
  "events": ["message.received", "message.status"],
  "active": true,
  "secret": "<o-segredo-de-assinatura>"
}

A URL precisa ser HTTPS e alcançável pela internet pública. URLs recusadas devolvem 400 VALIDATION_FAILED.

2. Os cinco eventos

message.echo costuma ser o esquecido, e é ele que mantém a sua caixa coerente com a realidade: se um operador responde pelo celular, você precisa saber. E message.revoked chega como evento próprio, não como status: failed — mensagem apagada não é mensagem que falhou.

3. O envelope

Todo POST tem exatamente cinco campos no corpo:

{
  "event": "message.received",
  "eventId": "evt_90311",
  "timestamp": "2026-08-13T18:12:03.000Z",
  "timestampUnix": 1786126323,
  "data": {
    "id": "msg_18273",
    "conversationId": "conv_991",
    "numberId": "num_4711",
    "direction": "inbound",
    "type": "text",
    "status": "received",
    "isSystemMessage": false,
    "from": {
      "phoneE164": "+5511999990000",
      "pushname": "Ana Ribeiro"
    },
    "text": { "body": "Oi, ainda dá tempo de participar?" },
    "mentionedIds": [],
    "timestamp": "2026-08-13T18:12:03.000Z",
    "timestampUnix": 1786126323,
    "statusHistory": []
  }
}

type: "reaction" — o emoji e a mensagem alvo

Quando alguém reage a uma mensagem, chega um message.received (ou message.echo, se a reação partiu do seu próprio aparelho) com type: "reaction" e um bloco reaction:

{
  "id": "msg_18291",
  "conversationId": "conv_991",
  "type": "reaction",
  "reaction": {
    "emoji": "😂",
    "messageId": "msg_18270"
  }
}

• reaction.messageId é a mensagem que RECEBEU a reação, no mesmo espaço msg_… de todo identificador nosso. Serve direto em GET /v1/messages/{id} — é assim que você prende o emoji no balão certo, como o WhatsApp faz.
• emoji vazio ("") significa que o remetente REMOVEU a reação. Não é “reação sem emoji”, e não existe um campo removed ao lado — a string vazia é a representação. O messageId continua presente: você precisa saber qual balão perdeu o emoji.
• messageId é omitido quando a mensagem reagida não pode ser resolvida nesta conversa — tipicamente porque ela é anterior ao pareamento do seu número. O bloco reaction continua presente com o emoji: conhecer o emoji não depende de conhecermos o alvo. O identificador do canal nunca aparece no lugar.
• O bloco só existe em type: "reaction". Mensagem de texto ou mídia não ganha reaction — a presença do bloco é o significado, como em revoked, failure e group.

connection.updated

{
  "event": "connection.updated",
  "eventId": "evt_90355",
  "timestamp": "2026-08-13T18:30:00.000Z",
  "timestampUnix": 1786127400,
  "data": {
    "numberId": "num_4711",
    "state": "disconnected",
    "previousState": "connected",
    "changedAt": "2026-08-13T18:30:00.000Z",
    "reason": null
  }
}

O numberId aqui é o mesmo identificador que aparece nos eventos de mensagem. É por ele que você correlaciona “este número caiu” com “estas conversas estão paradas”.

reason é sempre presente e null na esmagadora maioria das transições — é o mesmo campo, com os mesmos valores, que GET /v1/numbers/{id}/status publica. Quando vier preenchido, o pareamento foi recusado por divergência de telefone: o que fazer em cada caso. Trate valor desconhecido como “sem motivo declarado”.

4. Verificar a assinatura

Cada POST leva três headers:

X-Webhook-Id:         evt_90311
X-Webhook-Timestamp:  1786126323
X-Webhook-Signature:  sha256=<hex>

A assinatura é o HMAC-SHA256 desta string, com o seu segredo:

"<X-Webhook-Timestamp>" + "." + "<corpo cru da requisição>"

Implementação completa (Node/Express)

const crypto = require('crypto');
const express = require('express');

const app = express();
const SEGREDO = process.env.NUNTIS_WEBHOOK_SECRET;
const JANELA_SEGUNDOS = 300; // 5 minutos

/**
 * Verifica a assinatura de um POST do Nuntis.
 *
 * @param {Buffer} corpoCru  corpo exatamente como chegou
 * @param {string} timestamp header X-Webhook-Timestamp
 * @param {string} assinatura header X-Webhook-Signature ("sha256=...")
 * @returns {boolean}
 */
function assinaturaValida(corpoCru, timestamp, assinatura) {
  if (!corpoCru || !timestamp || !assinatura) return false;

  // 1. Rejeite o que estiver fora da janela ANTES de qualquer coisa.
  //    Sem isto, um POST capturado continua válido para sempre.
  const idade = Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp));
  if (!Number.isFinite(idade) || idade > JANELA_SEGUNDOS) return false;

  // 2. Recalcule o HMAC sobre "<timestamp>.<corpo cru>".
  const esperado =
    'sha256=' +
    crypto
      .createHmac('sha256', SEGREDO)
      .update(`${timestamp}.${corpoCru.toString('utf8')}`, 'utf8')
      .digest('hex');

  // 3. Compare em TEMPO CONSTANTE. Comparar com `===` vaza, pelo tempo de
  //    resposta, quantos caracteres do prefixo estavam certos — e isso é
  //    suficiente para forjar a assinatura byte a byte.
  const a = Buffer.from(assinatura, 'utf8');
  const b = Buffer.from(esperado, 'utf8');
  if (a.length !== b.length) return false;       // timingSafeEqual exige igual
  return crypto.timingSafeEqual(a, b);
}

app.post(
  '/hooks/nuntis',
  // ⚠️ express.raw() ANTES de qualquer express.json() nesta rota.
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const ok = assinaturaValida(
      req.body,                            // Buffer, corpo CRU
      req.get('X-Webhook-Timestamp'),
      req.get('X-Webhook-Signature'),
    );

    if (!ok) return res.sendStatus(401);

    const evento = JSON.parse(req.body.toString('utf8'));

    // At-least-once: o mesmo evento pode chegar mais de uma vez.
    if (await jaProcessado(evento.eventId)) return res.sendStatus(200);

    // Responda rápido; o trabalho pesado vai para a SUA fila.
    await enfileirar(evento);
    await marcarProcessado(evento.eventId);

    res.sendStatus(200);
  },
);

O timestamp entra dentro do material assinado justamente para que ninguém possa trocar por um timestamp novo sem ter o segredo. Verificar a janela sem incluir o timestamp na assinatura não protege nada.

5. Garantias de entrega

At-least-once — deduplique por eventId

O mesmo evento pode chegar mais de uma vez: um retry depois de timeout, uma reconciliação. Isso é escolha de desenho — perder mensagem é pior que repetir. Guarde os eventId já processados e ignore repetições. O valor é estável entre reentregas do mesmo fato.

Sem garantia de ordem — ordene por timestampUnix

read pode chegar antes de delivered. Confirmações atravessam a rede fora de ordem por natureza, e depois de uma reconexão chega uma rajada inteira de recibos atrasados. Nunca presuma sequência: ordene pelo campo, e nunca deixe um estado regredir no seu banco.

Responda 2xx em menos de 15 segundos

Fora disso a entrega é considerada falha e é retentada com backoff crescente por cerca de 6 horas. Depois disso o evento é perdido — e o caminho de recuperação é GET /v1/messages?since=….

Checklist do receptor

• Rota com raw body, antes de qualquer parser de JSON.
• Assinatura verificada em todo POST, com comparação em tempo constante.
• Janela de tempo rejeitada (~5 minutos).
• Deduplicação por eventId, persistida.
• Ordenação por timestampUnix; estado nunca regride.
• Resposta 2xx em menos de 15 s; processamento na sua fila.
• Segredo em cofre ou variável de ambiente, nunca em código.
• Valor desconhecido em event ou em enum: ignore, não quebre.

Nuntis — serviço de mensageria multicanal da Devari.