Webhook no n8n: receber as mensagens e conferir a assinatura

Monte no n8n um workflow que recebe o webhook da Coloquia, confere a assinatura de cada entrega e só depois segue com a mensagem.

O n8n é uma ferramenta de automação: cada mensagem que chega ao seu WhatsApp pode disparar um workflow nele. Este guia monta o começo desse workflow, que recebe a entrega e confere a assinatura antes de qualquer outra coisa. O que vem depois (responder, avisar alguém, chamar outra IA) fica por sua conta. O formato completo das entregas está em Webhook: receber as mensagens no seu servidor.

Serve o n8n Cloud ou um n8n seu, desde que o endereço dele seja https, público e na porta 443. Os nomes de nós e opções abaixo são os da interface em inglês do n8n.

1. O nó Webhook

  1. Crie um workflow novo e adicione o nó Webhook.
  2. Em HTTP Method, escolha POST. Em Respond, deixe Immediately: o n8n responde na hora, dentro dos 10 segundos que a Coloquia espera.
  3. Em Add Option, ligue Raw Body. Sem ele, o n8n entrega o JSON já lido, e a assinatura precisa do corpo exatamente como chegou.
  4. No topo do nó, escolha Production URL e copie o endereço. O Test URL só recebe enquanto o n8n está escutando um teste; com ele, as entregas falham e contam para o desligamento automático.
  5. Publique o workflow. Só depois disso o n8n passa a receber no Production URL.

2. Ligar o webhook na Coloquia

  1. Na área do cliente, abra Conectar a IA → Configurar o webhook, cole o endereço do n8n e clique em Salvar e ligar.
  2. Copie o segredo. Ele aparece uma única vez; se perder, use Gerar segredo novo e troque no nó do passo 3.

3. O nó Code que confere a assinatura

Logo depois do Webhook, adicione um nó Code em JavaScript, no modo Run Once for All Items, e cole o código abaixo. Troque cole aqui o segredo pelo segredo do passo 2, mantendo as aspas.

const crypto = require('crypto');
const SEGREDO = 'cole aqui o segredo';

const headers = $input.first().json.headers;
const timestamp = headers['x-coloquia-timestamp'] || '';
const recebida = Buffer.from(headers['x-coloquia-signature'] || '');
const corpo = await this.helpers.getBinaryDataBuffer(0, 'data');

const calculada = Buffer.from('sha256=' + crypto.createHmac('sha256', SEGREDO)
  .update(timestamp + '.').update(corpo).digest('hex'));
const recente = Math.abs(Date.now() / 1000 - Number(timestamp)) <= 300;
if (!recente || recebida.length !== calculada.length || !crypto.timingSafeEqual(recebida, calculada)) {
  throw new Error('Assinatura inválida: entrega descartada.');
}
const evento = JSON.parse(corpo.toString('utf8'));
if (evento.event_id !== headers['x-coloquia-id']) {
  throw new Error('Identificador diferente do cabeçalho: entrega descartada.');
}
return [{ json: evento }];

O código faz a mesma conta da Coloquia: sha256= seguido do HMAC-SHA256, com o segredo, de <timestamp>.<corpo>, usando os bytes do corpo como chegaram. Ele também recusa entregas com mais de 5 minutos e confere se o event_id do corpo é o mesmo do cabeçalho X-Coloquia-Id. Se algo não bate, a execução para com erro e nada segue adiante. A saída do nó é o evento, pronto para os próximos nós.

No n8n Cloud, o módulo crypto já está liberado no nó Code. Num n8n seu, libere com a variável de ambiente NODE_FUNCTION_ALLOW_BUILTIN=crypto.

O segredo fica visível para quem pode editar o workflow. Se alguém que não devia o viu, gere um segredo novo na Coloquia e troque no nó.

Publique o workflow de novo depois de colar o código.

4. Testar

  1. Na tela do webhook, clique em Enviar teste. A Coloquia manda um evento de exemplo, sem conteúdo de conversa, com event igual a webhook.test.
  2. No n8n, abra a aba Executions do workflow. A execução do teste deve aparecer com o nó Code concluído e o evento na saída. Se o Code parou com Assinatura inválida, confira se o segredo é o atual e se o Raw Body está ligado.

Antes de reagir às mensagens

  • Ignore os eventos com from_me igual a true se o seu workflow responde no WhatsApp. Sem isso, ele pode responder às próprias respostas, sem parar.
  • Ignore o teste (event igual a webhook.test) nos passos que agem de verdade.
  • A mesma entrega pode chegar mais de uma vez. Guarde o event_id (por exemplo, numa tabela) e não processe de novo o que já processou.
  • Se o n8n ficar fora do ar, a Coloquia tenta de novo por até cinco minutos. Depois de 50 eventos seguidos sem sucesso, o webhook é desligado e você recebe um e-mail.

Quer que o Grok Bot reaja às mensagens? Este workflow é o primeiro passo: veja Seu Grok Bot reagindo ao seu WhatsApp.