BLOG
Webhook whatsapp n8n: Webhook WhatsApp no n8n: passo a passo
Aprenda a montar um webhook WhatsApp n8n: receber mensagens, validar a assinatura HMAC e evitar duplicidade nas novas tentativas. Veja o passo a passo.

Para montar um webhook WhatsApp n8n seguro, você precisa de três coisas: um nó Webhook em POST com Raw Body ligado, a validação da assinatura HMAC-SHA256 em um nó Code e uma trava que impeça processar a mesma mensagem duas vezes. Este passo a passo mostra cada nó, com código e exemplos do dia a dia de quem atende pelo WhatsApp.
Principais pontos
- O nó Webhook precisa estar em POST com Raw Body ativado: a assinatura é calculada sobre o corpo bruto, não sobre o JSON reserializado.
- A validação do HMAC-SHA256 deve usar comparação em tempo constante (crypto.timingSafeEqual), nunca ===.
- Provedores de webhook entregam no mínimo uma vez: o mesmo evento pode chegar mais de uma vez.
- Responder 200 antes da lógica pesada (CRM, banco, IA) reduz reenvios desnecessários.
- A chave de idempotência é o ID da mensagem, não timestamp nem ID de execução do n8n.
- Reter só o necessário por 24 a 72 horas ajuda na minimização de dados prevista na LGPD.
Como funciona um webhook do WhatsApp no n8n
Um webhook é o caminho inverso de uma chamada de API. Em vez de você perguntar toda hora se chegou mensagem, o provedor avisa. Quando um evento acontece (um cliente escreveu, ou uma mensagem que você enviou foi entregue ou lida), ele faz um POST na URL do seu nó Webhook no n8n. Esse nó é o gatilho do workflow: tudo o que vem depois só roda porque o evento chegou.
O que chega no seu endpoint e quando
O corpo do POST é um JSON com o evento. Numa mensagem recebida, ele traz quem enviou, o conteúdo e um identificador da mensagem. Numa mudança de estado, traz o estado novo (na fila, enviada, entregue, lida). Esse identificador é a peça mais importante deste artigo, porque é ele que vai evitar duplicidade mais adiante.
Verificação (GET) e eventos (POST) são coisas diferentes
No padrão da Meta, o cadastro do webhook tem duas fases. Na primeira, o provedor faz uma chamada GET para confirmar que a URL é sua: se o hub.verify_token coincidir com o que você definiu, o endpoint responde 200 com o hub.challenge em texto puro. Está descrito na documentação da Meta sobre endpoints de webhook e em um guia em português sobre a configuração. Na segunda fase, os eventos reais chegam por POST, e a autenticidade deles é confirmada pela assinatura, não pelo token de verificação.
O mesmo raciocínio vale para quem busca por webhook WhatsApp API ou webhook WhatsApp Business: receber, validar a origem, responder rápido e não repetir efeito.
Onde entram os webhooks assinados do FlowZap
O FlowZap envia webhooks assinados, com novas tentativas, e também oferece eventos em tempo real (SSE). A API e os webhooks estão em todos os planos (veja os planos). Antes de copiar qualquer código deste artigo, confira em /docs o nome exato do cabeçalho de assinatura, onde fica o segredo e quais eventos estão disponíveis. Os nomes usados aqui seguem o padrão x-hub-signature-256; a documentação é a referência final.
Passo a passo: webhook WhatsApp n8n com Raw Body
Este é o trecho do whatsapp n8n trigger: o nó Webhook é o gatilho que inicia o workflow. Siga a ordem.
Nó 1: Webhook em POST com Raw Body
- Crie um workflow novo e adicione o nó Webhook.
- Em HTTP Method, escolha POST.
- Defina um Path que não seja óbvio, por exemplo
whatsapp-eventos-a8f3. - Em Options, ative Raw Body.
- Em Respond, escolha a opção que permite responder por um nó Respond to Webhook mais adiante.
O Raw Body é obrigatório porque a assinatura é calculada sobre os bytes exatos que o provedor enviou. Se o n8n converter o corpo em JSON e reserializar, chaves podem mudar de ordem, espaços somem, e o hash que você calcula deixa de bater com o do cabeçalho. Resultado: assinatura sempre inválida, mesmo com o segredo certo.
URL de teste x URL de produção
O nó mostra duas URLs. A de teste só recebe eventos enquanto você clica em escutar no editor, e serve para ver o formato do payload. A de produção só funciona com o workflow ativo. Quem cadastra a URL de teste no provedor e depois estranha o silêncio em produção costuma ter esquecido de ativar o workflow e trocar a URL. A documentação oficial do nó Webhook explica essa diferença.
Se você desenvolve na sua máquina, o provedor não alcança localhost. Nesse caso, é preciso expor a porta por um túnel, como mostra este artigo sobre webhook em localhost. Use isso só para teste.
Cadastrar a URL no FlowZap
Com o workflow ativo, copie a URL de produção e cadastre-a como destino de webhook no FlowZap, junto com o segredo de assinatura. O caminho exato no console e a lista de eventos estão em /docs. Guarde o segredo em um lugar seguro: você vai usá-lo no próximo nó.
Como validar a assinatura do webhook no n8n
Esta é a seção que responde à dúvida mais comum: como validar assinatura de webhook sem errar o cálculo.
Por que validar: qualquer um pode chamar a sua URL
A URL do webhook é só um endereço na internet. Se ela vazar, qualquer pessoa pode mandar um POST com um JSON que parece uma mensagem de cliente. Sem validação, o seu fluxo cria contato falso no CRM, dispara resposta para um número inventado ou alimenta a sua IA com texto forjado. A assinatura prova que o corpo veio de quem tem o segredo e que não foi alterado no caminho.
O padrão usado pela Meta, e seguido por gateways compatíveis, é este: o remetente calcula um HMAC-SHA256 do corpo bruto usando o segredo e envia o resultado no cabeçalho x-hub-signature-256, no formato sha256=. Detalhes em documentação da Meta, fórum de desenvolvedores e guia de verificação de webhooks.
Nó 2: Code com HMAC-SHA256
Adicione um nó Code (modo Run Once for All Items) logo depois do Webhook. Exemplo em JavaScript:
const crypto = require('crypto');
const item = $input.first();
const raw = await this.helpers.getBinaryDataBuffer(0, 'data');
const recebida = String(item.json.headers['x-hub-signature-256'] || '');
const esperada = 'sha256=' + crypto
.createHmac('sha256', $env.WEBHOOK_SECRET)
.update(raw)
.digest('hex');
const a = Buffer.from(recebida);
const b = Buffer.from(esperada);
const valida = a.length === b.length && crypto.timingSafeEqual(a, b);
return [{ json: { valida, body: valida ? JSON.parse(raw.toString('utf8')) : null } }];
O que o código faz: lê o corpo bruto (por isso o Raw Body), pega o cabeçalho, calcula o HMAC, monta a string com o prefixo sha256= e compara. Só depois de validar ele converte o corpo em objeto.
Três cuidados práticos:
- Segredo fora do código. Use uma credencial ou variável de ambiente do n8n, nunca o texto do segredo dentro do workflow. Em instalações próprias, o acesso a
$enve ao módulocryptopode precisar ser liberado na configuração; confira na sua versão. - Nome do cabeçalho. Em /docs do FlowZap, confirme o cabeçalho e o formato da assinatura antes de colar o código. Se for diferente, ajuste a linha da variável
recebidae o prefixo. - Nome do campo do corpo bruto. No exemplo, o binário se chama
data, que é o padrão do nó. Se o seu estiver diferente, ajuste.
Comparação segura com timingSafeEqual
Por que não usar recebida === esperada? A comparação simples de texto pode parar no primeiro caractere diferente, e a diferença de tempo de resposta pode, em tese, ser medida por quem ataca o endpoint (timing attack). A função crypto.timingSafeEqual leva o mesmo tempo independentemente de onde está a diferença. Ela exige buffers do mesmo tamanho, por isso o código checa a.length === b.length antes.
Nó 3: If e resposta 401
Depois do Code, adicione um nó If com a condição {{ $json.valida }} igual a verdadeiro.
- Ramo falso: conecte a um Respond to Webhook com código 401 (ou 403) e termine o fluxo ali. Não grave nada, não chame nenhuma API.
- Ramo verdadeiro: segue para a checagem de duplicidade, na próxima seção.
Novas tentativas: como evitar processar a mesma mensagem duas vezes
Assinatura válida não significa evento novo. O mesmo evento pode chegar duas vezes, ambas com assinatura correta.
Entrega no mínimo uma vez: o duplicado vai acontecer
Provedores de webhook trabalham com entrega at-least-once: se o seu endpoint falha, oscila ou demora além do tempo limite, ele reenvia o mesmo evento. Isso é comportamento esperado, não defeito. O guia da Hookdeck sobre webhooks do WhatsApp e este checklist da comunidade n8n tratam desse ponto.
Um exemplo do dia a dia: o cliente manda 'quero o boleto'. Seu workflow cria um cartão no CRM, consulta um sistema financeiro lento e responde. Como a consulta demorou, o provedor não recebeu o 200 a tempo e reenviou. Agora existem dois cartões no CRM e o cliente recebeu duas respostas.
Responder primeiro, trabalhar depois
A primeira defesa é responder 200 logo no início, antes das etapas pesadas (CRM, banco, IA). A ordem fica: validar, checar duplicidade, responder 200 e só então executar a lógica. Essa prática aparece em discussões da comunidade n8n, como esta sobre idempotência e esta sobre retentativas sem duplicidade.
Chave de idempotência: use o ID da mensagem
A chave que identifica 'este evento já foi visto' deve ser o ID estável da mensagem no payload (por exemplo message.id ou event_id, conforme o evento). Evite:
- Timestamp de entrega: muda a cada tentativa.
- ID de execução do n8n (
$execution.id): cada reenvio gera uma execução nova, então a chave nunca se repete.
Guarda no Redis ou em tabela com UNIQUE
Você tem duas opções, ambas atômicas:
- Redis:
SET lock:msg_ID processing EX 86400 NX. ONXsó grava se a chave não existir; oEX 86400expira em 24 horas. Se o comando não gravar, o evento já foi visto. - Banco de dados:
INSERTem uma tabela com restriçãoUNIQUE(message_id). Se o banco recusar por duplicidade, o evento já foi visto.
O ponto crítico é checar e gravar no mesmo passo. Consultar 'existe?' e depois gravar em dois nós separados deixa uma brecha quando duas execuções rodam ao mesmo tempo, como no modo fila.
O FlowZap também faz novas tentativas dos webhooks; as regras estão em /docs. Em resumo:
| Situação | O que fazer |
|---|---|
| Assinatura inválida | Responder 401 e encerrar, sem gravar nada |
| ID de mensagem novo | Gravar a chave, responder 200 e seguir para a lógica |
| ID já registrado | Responder 200 e encerrar, sem refazer nada |
| Lógica pesada falhou depois do 200 | Tratar o erro no próprio workflow (alerta, fila de reprocessamento), pois o provedor não vai reenviar |
Workflow completo de WhatsApp no n8n: os 6 nós em ordem
Juntando as peças, este é o workflow completo, na ordem que importa.
Ordem recomendada dos nós
| Nó | Tipo | Função |
|---|---|---|
| 1 | Webhook | Recebe o POST, com Raw Body ligado |
| 2 | Code | Calcula o HMAC-SHA256 e compara com o cabeçalho |
| 3 | If | Assinatura inválida: Respond to Webhook com 401 e fim |
| 4 | Redis ou banco | Grava o ID da mensagem de forma atômica; se já existe, 200 e fim |
| 5 | Respond to Webhook | Responde 200 para barrar novas tentativas |
| 6+ | Lógica de negócio | CRM, resposta, aviso à equipe, IA |
A ordem tem uma razão: validar antes de gravar qualquer coisa, e deduplicar antes de qualquer efeito colateral (criar cartão, enviar mensagem, notificar alguém). Inverter isso é o jeito mais comum de ver o mesmo cliente atendido duas vezes.
Exemplos para n8n do FlowZap como ponto de partida
O FlowZap tem exemplos para n8n (e para Make). Em /docs você encontra o caminho para eles. Trate o exemplo como o seu whatsapp n8n template: importe, troque a URL e o segredo, e confira o cabeçalho de assinatura antes de ativar.
Um detalhe de escopo: o nó nativo de WhatsApp do n8n e a chamada HTTP à API do FlowZap são caminhos diferentes. Aqui o foco é receber eventos pelo webhook. Para responder, o caminho é chamar a API do FlowZap com uma requisição HTTP. Se você ainda está decidindo entre API e outras formas de conectar o número, leia as vantagens de usar uma API como o FlowZap.
Lógica de negócio: CRM, resposta e IA
Depois do nó 5, a automação WhatsApp n8n começa de fato. Ideias que cabem num fluxo assim:
- Registrar ou atualizar o contato quando chega a primeira mensagem.
- Avisar a equipe no canal interno quando o cliente escreve fora do horário.
- Mover o contato para uma etapa do funil quando ele manda uma palavra-chave.
- Responder pela API do FlowZap com uma mensagem montada a partir de um modelo.
Para mais ideias de fluxos de atendimento, cobrança e lembretes, veja os casos de uso. E lembre: mensagens ativas só devem ir para quem autorizou o contato.
Segurança e LGPD no webhook
Um webhook recebe dados pessoais: telefone, nome e o conteúdo da conversa. Por isso, a segurança dele não é só uma questão técnica. Nada aqui substitui a orientação do seu jurídico; é um ponto de partida.
Assinatura como medida técnica de segurança
A Lei nº 13.709/2018 (LGPD), no art. 46, pede medidas técnicas e administrativas para proteger dados pessoais de acessos não autorizados e de alterações indevidas. Validar a assinatura ajuda a garantir a origem e a integridade do que entra no seu fluxo. Um webhook aberto, ao contrário, permite que alguém injete dados forjados no seu CRM.
A ANPD reúne orientações sobre incidentes de segurança (art. 48 e Resolução CD/ANPD nº 15/2024) em materiais no gov.br. Nem todo caso é incidente de comunicação obrigatória, e quem avalia isso é a sua empresa, com apoio jurídico. Ter assinatura validada, segredo guardado e registro do que aconteceu facilita essa avaliação. O guia da ANPD também é uma boa leitura de apoio.
Guardar só o necessário e por pouco tempo
O princípio da necessidade (art. 6º, III) vale também para a deduplicação. Duas regras simples:
- Guarde só o ID. Para saber se um evento já foi processado, o identificador basta. Não precisa gravar a mensagem inteira no Redis ou na tabela de controle.
- Use TTL curto. Um prazo de 24 a 72 horas cobre a janela de novas tentativas do provedor. Depois disso, a chave pode expirar. No Redis, o
EX 86400do exemplo já equivale a 24 horas; em tabela, agende uma limpeza.
Por fim, o histórico de execuções do n8n também guarda dados dos payloads. Revise por quanto tempo a sua instalação mantém as execuções salvas.
Erros comuns e como testar o webhook
Se algo não funciona, quase sempre é um destes problemas.
A assinatura nunca bate
- Causa provável: Raw Body desligado, segredo errado, cálculo feito sobre o JSON reserializado ou prefixo
sha256=esquecido na comparação. - Solução: ative Raw Body, confira o segredo cadastrado no FlowZap e compare a string completa, com prefixo. O fórum de desenvolvedores e o guia de verificação mostram esses mesmos tropeços.
Eventos duplicados mesmo com a deduplicação
- Causa provável: chave baseada em timestamp ou em
$execution.id; checagem e gravação em passos separados, o que abre brecha no modo fila. - Solução: use o ID da mensagem e um comando atômico (
SET ... NXouINSERTcomUNIQUE). Veja as discussões da comunidade sobre execuções duplicadas.
Timeout e 'workflow inativo'
- Causa provável: lógica pesada antes do Respond to Webhook; workflow não ativado; URL de teste usada em produção.
- Solução: mova o 200 para logo depois da deduplicação, ative o workflow e cadastre a URL de produção, conforme a documentação do nó.
Como testar
- Envie a mesma requisição duas vezes e confira que só a primeira gera efeito (um cartão no CRM, uma resposta).
- Altere um byte do corpo mantendo a assinatura antiga e confira que o fluxo responde 401.
- Derrube temporariamente a etapa de lógica e confira que o 200 já foi enviado antes.
Próximos passos
Confira em /docs os eventos, o cabeçalho e o segredo de assinatura. Os planos estão em /precos: o Start custa R$ 49 por mês e a API e os webhooks estão em todos os planos. O cadastro não pede cartão de crédito, mas não há teste grátis. Se ficar alguma dúvida, a equipe responde em /contato.
Comece com o FlowZap
Veja o que o FlowZap faz e compare os planos. Para criar a conta, basta o nome da empresa, um e-mail e uma senha: o cadastro não pede cartão de crédito, e o pagamento é por Pix ou cartão de crédito, sem fidelidade.
Perguntas frequentes
Como validar a assinatura de um webhook do WhatsApp no n8n?
Ative Raw Body no nó Webhook, leia o cabeçalho x-hub-signature-256 e calcule o HMAC-SHA256 do corpo bruto com o segredo em um nó Code. Compare com 'sha256=' mais o resultado usando crypto.timingSafeEqual. Se não bater, responda 401 e encerre o fluxo.
Por que o nó Webhook do n8n precisa do Raw Body?
Porque a assinatura é calculada sobre os bytes exatos enviados. Se o n8n converter o corpo em JSON e reserializar, a ordem das chaves e os espaços podem mudar, e o hash que você calcula deixa de coincidir com o do cabeçalho.
O que fazer quando o mesmo evento do WhatsApp chega duas vezes no n8n?
Use o ID estável da mensagem como chave de idempotência e grave-o de forma atômica, com SET NX no Redis ou INSERT em tabela com UNIQUE. Se o ID já existir, responda 200 e encerre. Não use timestamp nem o ID de execução do n8n.
Posso usar o mesmo workflow para webhook WhatsApp API e WhatsApp Business?
O raciocínio é o mesmo: receber por POST, validar a assinatura, responder 200 e deduplicar. O que muda é o nome do cabeçalho, o segredo e o formato dos eventos. No FlowZap, confira esses detalhes em /docs antes de ativar.
Por quanto tempo devo guardar o ID da mensagem para deduplicar?
Entre 24 e 72 horas costuma bastar, pois cobre a janela de novas tentativas do provedor. Guarde apenas o ID, não a mensagem inteira, e deixe a chave expirar. Isso ajuda no princípio da necessidade da LGPD.
Fontes
Atenda o WhatsApp da empresa em equipe.
Conecte o número por QR code e responda pelo navegador, com a API para integrar seus sistemas.
Cadastro sem cartão de crédito · Pix ou cartão de crédito, sem fidelidade


