Pular para o conteúdo
apiwpp
Integração

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

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:

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:

CampoValor
MethodPOST
URLhttps://api.apiwpp.com/connections/SEU_CONNECTION_ID/send
AuthenticationGeneric Credential Type → Header Auth, com a credencial acima
Send BodyLigado, 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:

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:

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.

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.

Conecte seu primeiro número hoje.

7 dias grátis, sem cartão de crédito.