Recurso em beta: pode mudar. O formato do corpo que o nó Webhook do n8n entrega ao seu fluxo (
body,headers,query) não foi conferido contra um n8n real.
Gatilhos, limites e proteções comuns estão na visão geral dos bots.
Situação: versão beta, em fase de testes.
Para que serve?
É o tipo mais livre. Em vez de a ProxyBox falar com uma plataforma pronta, você decide o que responder: consulta o pedido no seu banco, chama o seu CRM, passa por um modelo de IA de sua escolha, aplica regras de negócio e devolve o texto. Serve para quem usa n8n, Make, Zapier (com o gatilho de webhook), um servidor Laravel, Express ou Flask, e para plataformas que não têm tipo próprio (Langflow, Botpress e outras).
Como configuro?
curl -X PUT "https://proxybox.com.br/api/whatsapp/v1/integrations/bot" \
-H "apikey: SUA_CHAVE" -H "Content-Type: application/json" \
-d '{
"type": "webhook",
"enabled": true,
"url": "https://n8n.suaempresa.com.br/webhook/whatsapp-bot",
"api_key": "UM_TOKEN_SEU",
"api_key_header": "X-Meu-Token",
"signing_secret": "",
"history_messages": 10,
"send_history": true,
"trigger": "all",
"ignore_groups": true
}'
| Campo | Para que serve |
|---|---|
url |
Seu endereço https público |
api_key |
Opcional: um token que a ProxyBox envia como Authorization: Bearer, ou no cabeçalho de api_key_header |
signing_secret |
O segredo da assinatura; se deixar vazio, a ProxyBox gera um e mostra uma única vez |
send_history |
Se verdadeiro, o envelope leva as últimas mensagens da conversa |
history_messages |
Quantas (0 a 20) |
Como é o pedido que o seu servidor recebe?
POST https://n8n.suaempresa.com.br/webhook/whatsapp-bot
Content-Type: application/json
X-ProxyBox-Signature: t=1794416769,v1=3f2a...e91c
{
"event": "bot.message",
"session": { "id": "bs_8f2c1d", "new": true },
"chat": { "id": "5547999999999", "is_group": false, "name": "Maria" },
"instance": { "slug": "atendimento-da-loja" },
"text": "Qual o status do pedido 4512?",
"messages": [ { "id": "3EB0A1", "type": "text", "text": "Qual o status do pedido 4512?" } ],
"history": [ { "role": "user", "content": "Oi" }, { "role": "assistant", "content": "Olá! Como posso ajudar?" } ],
"sent_at": "2026-11-12T10:00:00-03:00"
}
session.newé verdadeiro na primeira mensagem de uma sessão nova.messagestraz as mensagens do turno (mais de uma se você usa o agrupamento).history(lista deroleecontent) só vem sesend_historyestiver ligado (o padrão é ligado) e houver conversa anterior.
Quer rodar isto agora? O sandbox é grátis, não precisa de número e já vem com a chave da API.
Testar grátisComo confiro a assinatura?
O esquema é o mesmo do aviso automático: X-ProxyBox-Signature: t=<unix>,v1=<hex>, em que v1 é o HMAC-SHA256 de "<t>.<corpo bruto>" com o segredo do bot. Rejeite o pedido se a assinatura não bater ou se t estiver mais de 5 minutos distante. Um exemplo mínimo em Node:
import crypto from "node:crypto";
import express from "express";
const app = express();
app.post("/whatsapp-bot", express.raw({ type: "application/json" }), async (req, res) => {
const h = Object.fromEntries((req.header("x-proxybox-signature") || "").split(",").map((p) => p.split("=")));
const ok = crypto.createHmac("sha256", process.env.BOT_SEGREDO).update(`${h.t}.${req.body.toString("utf8")}`).digest("hex") === h.v1
&& Math.abs(Date.now() / 1000 - Number(h.t)) < 300;
if (!ok) return res.sendStatus(401);
const ev = JSON.parse(req.body);
res.json({ reply: `Recebi: ${ev.text}` });
});
app.listen(3000);
Que respostas a ProxyBox aceita?
| Você devolve | Efeito |
|---|---|
{"reply": "texto"} |
Uma mensagem |
{"replies": ["a", "b"]} |
Várias mensagens, em ordem |
{"actions": [{"type":"text","text":"..."}, {"type":"image","url":"https://..."}, {"type":"end"}, {"type":"handoff"}]} |
Texto, imagem, encerrar a sessão (end) ou passar para uma pessoa (handoff) |
Uma lista de itens, ou as chaves output, text ou message |
Aceitos, para facilitar o uso com nós do n8n |
204 ou corpo vazio |
Não responder |
O texto Workflow got started. (que o n8n devolve quando o nó Webhook está em Immediately) é recusado com aviso: o fluxo precisa responder com o resultado.
Como configuro o n8n?
- Crie um fluxo com o nó Webhook (POST). Em Respond, escolha When Last Node Finishes (ou use o nó Respond to Webhook).
- Cole a Production URL no campo
url. - Se quiser autenticar, ative Header Auth no nó Webhook com o mesmo nome e valor de
api_key_headereapi_key. - Confira a assinatura em um nó Code (modelo no guia WhatsApp no n8n).
- No final do fluxo, devolva
{ "reply": "..." }.
O n8n entrega o corpo da chamada dentro de body (com headers e query ao lado); o seu fluxo deve ler {{$json.body.text}}. Esse formato segue o conhecimento do n8n e não foi conferido nesta rodada contra um n8n real. Se você usa o pacote de nós da ProxyBox, o gatilho dele cuida da assinatura.
Quais limites valem?
- 15 segundos para responder (conexão de 5). Acima disso, é erro; se o seu fluxo é demorado, responda rápido com uma frase de espera e envie o resultado depois pela API.
- Resposta de até 1 MB.
- Endereço https público, sem redirecionamento.
- As travas do número valem para a resposta: ritmo, não perturbe e trava de contato novo.
- Máximo de 20 respostas por hora por conversa e 200 por dia.
E a memória?
Quem decide é você. Com send_history, o envelope traz as últimas mensagens; sem ele, o seu fluxo recebe só a mensagem atual e deve guardar o contexto do seu lado (por exemplo, no banco, pelo chat.id).
Erros comuns
| Sintoma | Causa provável |
|---|---|
| "Workflow got started." recusado | Nó Webhook do n8n em Immediately |
Estado error |
Assinatura recusada, resposta lenta, resposta não JSON |
| Respostas duplicadas | O seu fluxo também envia pela API além de devolver reply |
| Nada acontece | Gatilho keyword, grupo ignorado ou 204 |
Veja também
- Bots de WhatsApp pela API: tipos e limites
- Nós n8n para a API de WhatsApp: instalar
- Webhook da API de WhatsApp: eventos e assinatura
- 13 modelos para a API de WhatsApp (Woo, Asaas)
Índice completo: todos os guias. Sobre o produto: instância de WhatsApp com chave própria.
Autoria: equipe técnica da ProxyBox. Atualizado em 11/11/2026. Fonte do formato do n8n: documentação pública do nó Webhook, lida em 11/11/2026. Recurso em beta.