WhatsApp no n8n com a apiwpp: enviar com HTTP Request e receber com Webhook
Envie e receba mensagens de WhatsApp no n8n com os nós HTTP Request e Webhook, credencial Header Auth, filtro por tipo de evento e assinatura HMAC.
Atualizado em
O n8n conversa com qualquer API HTTP, e é assim que ele funciona com a apiwpp. Não existe um nó nativo da apiwpp no n8n: o envio usa o nó HTTP Request, que chama a API como qualquer outro sistema, e o recebimento usa o nó Webhook, que recebe os eventos que a apiwpp envia. Com esses dois nós você monta respostas automáticas, avisos de pedido ou a ponte entre o WhatsApp e o seu CRM, sem escrever um servidor.
O que você precisa
- Uma conta na apiwpp: o teste grátis de 7 dias libera 1 número com os recursos do plano PRO, sem cartão.
- Um número conectado ao projeto, por QR code ou código de pareamento.
- Uma chave de API do projeto com o escopo
messages:send. - O n8n na nuvem ou instalado no seu servidor, acessível por uma URL https pública para receber os eventos.
Anote o identificador da conexão (o número dentro do projeto): ele entra na URL de envio.
Criar a credencial Header Auth
A apiwpp autentica pelo cabeçalho Authorization com a chave no formato Bearer. No n8n, guarde isso numa credencial, para a chave não aparecer dentro dos nós:
- Em Credentials, crie uma credencial do tipo Header Auth.
- Em Name, escreva
Authorization. - Em Value, escreva
Bearerseguido de um espaço e da chave (wag_live_…).
A mesma credencial serve para todos os workflows que enviam mensagens pelo projeto. Se a chave for rotacionada, basta trocar o valor aqui.
Enviar uma mensagem com o nó HTTP Request
Adicione um nó HTTP Request depois do gatilho do seu workflow (um formulário, uma linha nova na planilha, um pedido no e-commerce) e configure:
| Campo | Valor |
|---|---|
| Method | POST |
| URL | https://api.apiwpp.com/connections/SEU_CONNECTION_ID/send |
| Authentication | Generic Credential Type → Header Auth, com a credencial acima |
| Send Body | Ligado, no formato JSON |
No corpo, use o modo JSON e as expressões do n8n para preencher os campos a partir do item anterior:
{
"to": "{{ $json.telefone }}",
"message": "Olá, {{ $json.nome }}! Seu pedido {{ $json.pedido }} foi confirmado.",
"clientRef": "pedido-{{ $json.pedido }}"
}
O campo to leva só dígitos, com o código do país e o DDD (5511988887777). A resposta é 202 com jobId, scheduledAt e position: a mensagem entrou na fila do número, que envia num ritmo que protege o número de bloqueios. O resultado chega depois, pelo webhook.
O clientRef é a proteção contra duplicidade: se o workflow rodar de novo para o mesmo pedido, a API responde 200 com o job original e "duplicate": true, sem enviar outra mensagem. Use sempre um identificador que já existe no seu processo. Se a mensagem tiver aspas ou quebras de linha vindas de outro nó, monte o corpo com a expressão {{ JSON.stringify(...) }} ou num nó Set, para o JSON continuar válido.
Tratar erros e o limite de destinatários novos
Os erros vêm em JSON com o campo error. Em Settings do nó HTTP Request, ligue Continue On Fail (ou a saída de erro) para tratar a resposta em vez de parar o workflow:
400: corpo inválido ou conexão fora do statusopen. Corrija o corpo ou espere a reconexão do número.429comnew_recipient_cap_reached: o número chegou ao teto de destinatários novos das últimas 24 horas. Nada entrou na fila; a resposta traz o cabeçalhoRetry-After, em segundos. Um nó Wait com esse tempo, seguido de uma nova tentativa com o mesmoclientRef, resolve.
Mensagens para contatos que já conversaram com o número continuam sendo aceitas mesmo com o teto atingido. Os limites de ritmo estão em fila com ritmo anti-bloqueio.
Receber eventos com o nó Webhook
Crie um workflow que começa com um nó Webhook, com HTTP Method POST e resposta imediata. O n8n mostra duas URLs: a de teste, que só escuta enquanto você clica em ouvir o evento, e a de produção, que funciona com o workflow ativo. Configure a URL de produção como o endereço de webhook do projeto na apiwpp.
O projeto tem um único endereço de webhook, que recebe todos os eventos de todos os números dele. Se o n8n cuida só de uma parte do trabalho, vale criar um projeto separado para ele: projetos não têm custo.
Cada evento chega com o mesmo envelope, que o n8n coloca em $json.body:
{
"type": "message.incoming",
"connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
"tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
"externalId": "loja-42",
"timestamp": "2026-09-25T12:00:02.000Z",
"data": { "messageId": "3EB0C767D26A1D8A3F52", "phone": "+5511988887777" }
}
Responda rápido: a apiwpp espera um status 2xx em até 10 segundos e tenta de novo, até 6 vezes, uma entrega que falhou.
Filtrar por tipo de evento
Depois do Webhook, um nó Switch com a expressão {{ $json.body.type }} separa os caminhos:
message.incoming: alguém escreveu para o número. Siga para a resposta automática, o CRM ou a planilha.message.delivery: o status de uma mensagem enviada mudou (sent,delivered,readoufailed). OclientRefvem junto, para atualizar o registro certo.connection.status: o número conectou ou caiu. Um aviso por e-mail ou Slack quandowillReconnectfor falso evita surpresas.- Qualquer outro tipo: deixe cair numa saída sem ação. A lista de eventos só cresce, e um tipo desconhecido não deve quebrar o workflow.
A entrega é pelo menos uma vez: o mesmo evento pode chegar duas vezes. Antes de gravar ou responder, confira se o data.messageId já foi processado, por exemplo numa tabela do seu banco ou numa planilha.
Verificar a assinatura HMAC num nó Code
Com um segredo definido no projeto, cada entrega traz X-Sales-Timestamp e X-Sales-Signature (sha256= seguido do HMAC-SHA256 de timestamp + "." + corpo bruto). Para conferir, ligue a opção Raw Body no nó Webhook e adicione um nó Code logo depois:
const crypto = require('crypto')
const secret = $env.APIWPP_WEBHOOK_SECRET
if (!secret) throw new Error('APIWPP_WEBHOOK_SECRET is not set')
const item = $input.first()
const raw = await this.helpers.getBinaryDataBuffer(0, 'data')
const timestamp = item.json.headers['x-sales-timestamp'] ?? ''
const signature = item.json.headers['x-sales-signature'] ?? ''
const fresh = /^\d+$/.test(timestamp) && Math.abs(Date.now() / 1000 - Number(timestamp)) <= 300
const mac = crypto.createHmac('sha256', secret).update(`${timestamp}.`).update(raw).digest('hex')
const expected = Buffer.from(`sha256=${mac}`)
const received = Buffer.from(signature)
if (!fresh || expected.length !== received.length || !crypto.timingSafeEqual(expected, received)) {
throw new Error('invalid webhook signature')
}
return [{ json: JSON.parse(raw.toString('utf8')) }]
No n8n instalado no seu servidor, o nó Code só carrega o módulo crypto se a variável NODE_FUNCTION_ALLOW_BUILTIN o permitir, e o acesso a $env depende da configuração da instância; confira a documentação do n8n para a sua versão. O que é HMAC e por que comparar em tempo constante está no glossário, e o passo a passo completo no tutorial WhatsApp no n8n.
Perguntas frequentes
Existe um nó da apiwpp no n8n?
Não. A integração usa os nós genéricos do n8n: HTTP Request para enviar e Webhook para receber. Como a apiwpp é uma API REST com JSON e eventos por webhook, esses dois nós cobrem o envio, o recebimento e o tratamento de erros.
Posso usar a URL de teste do nó Webhook na apiwpp?
Só enquanto testa. A URL de teste escuta apenas quando você pede para ouvir um evento no editor. Para o uso real, ative o workflow e configure a URL de produção como endereço de webhook do projeto.
O workflow pode enviar centenas de mensagens de uma vez?
A API aceita os envios, mas a fila de cada número respeita o ritmo padrão de 3 por minuto, 60 por hora e 200 por dia, com no máximo 100 destinatários novos por 24 horas. Os envios saem aos poucos, e o scheduledAt de cada resposta diz quando.
Como evitar mensagens repetidas se o workflow rodar de novo?
Mande sempre um clientRef ligado ao seu registro, como o número do pedido. A repetição com o mesmo clientRef devolve o job original sem enviar de novo, por até 7 dias.
Outras integrações
Todos: Integrações →Sem app nativo da apiwpp no Make: o envio usa o módulo HTTP "Make a request", os eventos chegam num Custom webhook, e o cenário de exemplo transforma cada nova linha da planilha numa mensagem.
Sem app nativo da apiwpp no Zapier: a ação POST do Webhooks by Zapier envia a mensagem com o cabeçalho Authorization, o gatilho Catch Hook recebe os eventos, e a fila do número dita o ritmo.
Envie mensagens com requests, trate 400 e 429 com Retry-After e receba os eventos num endpoint Flask ou FastAPI que verifica a assinatura HMAC-SHA256 com hmac.compare_digest.