Recurso em beta: pode mudar. Quase todos os mecanismos novos citados aqui (IPs permitidos, papéis, aprovação, integrações) são da versão 1.2 e estão em beta. Esta página descreve o que foi construído e testado, não uma certificação: a ProxyBox não tem auditoria externa de segurança desta API e não afirma ter.
Atualização de 12/11/2026 (provado em aparelho real): um IP permitido que deixaria o cliente de fora foi recusado, e o status desligado devolveu
403. Não houve auditoria externa.
Como é a chave?
- Formato:
pbwa_seguido de 40 caracteres. Aparece uma única vez, ao criar a instância ou gerar a chave nova. - Guarda: só o hash (sha256) e os quatro últimos caracteres. A ProxyBox não consegue mostrar a chave de novo.
- Escopo: abre somente a instância dela. Quem cuida de um número não alcança os outros. Não há chave global da conta.
- Troca:
Gerar chave novano painel; a anterior morre na hora. Se suspeitar de vazamento, troque. - Em log: a chave nunca é escrita em registro, resposta de erro ou tela do admin.
Boas práticas: guarde em variável de ambiente ou cofre, nunca no código nem em repositório; use chaves diferentes por ambiente (teste e produção) com instâncias diferentes; e nunca coloque a chave em código que roda no navegador do usuário.
Como restrinjo quem usa a chave?
Com os IPs permitidos: até 20 IPs ou faixas. Quem chamar de outro IP recebe 403 ip_not_allowed. Vale na API v1 e nas rotas no estilo da Evolution e da Z-API. O painel (sessão) não depende dela. A API recusa uma lista que deixaria de fora o seu próprio IP.
Quem na minha equipe vê o quê?
Pelos papéis: visualizador e operador. Nenhum dos dois vê a chave, os avisos, os ajustes, os IPs ou as integrações. Para dar acesso a um sistema, entregue a chave (de preferência com IPs permitidos), e o uso fica na atividade.
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 sei que um aviso veio da ProxyBox?
Todo aviso leva X-ProxyBox-Signature: t=<unix>,v1=<hex>, em que v1 é o HMAC-SHA256 de "<t>.<corpo bruto>" com o segredo do aviso da instância. Confira com comparação em tempo constante e rejeite quando t estiver a mais de 5 minutos do seu relógio. O código em quatro linguagens está no guia do aviso automático. O mesmo esquema vale para o bot por webhook. Use também o uid para ignorar repetições. Se o seu sistema só aceita conexões de endereços conhecidos, libere os IPs de saída dos avisos listados no mesmo guia.
O que impede a ProxyBox de ser usada para atacar redes internas?
Tudo o que a ProxyBox acessa por endereço que você informa (aviso, bot, Chatwoot, S3, mídia por URL) passa por uma guarda de rede:
- só https, portas 443 e 8443, sem usuário e senha na URL;
- o nome é resolvido na hora e todos os IPs devem ser públicos; são negados IP privado, loopback, metadados de nuvem (169.254.169.254), faixa CGNAT, IPv4 embutido em IPv6, o próprio site e os servidores da ProxyBox;
- a conexão é presa ao IP conferido, para que uma troca de DNS depois da checagem não funcione;
- sem redirecionamento; tempo limite curto e tamanho máximo de resposta.
O objetivo é impedir que alguém cadastre um endereço apontando para a rede interna e use a ProxyBox como ponte (ataque conhecido como SSRF). A mídia que você manda por URL também é conferida antes de qualquer envio. Uma mensagem recebida é tratada como entrada hostil: o bot e o conector de IA nunca executam o que ela diz como se fosse ordem.
O que é cifrado?
| Dado | Como é guardado |
|---|---|
| Chave da instância | Só o hash |
| Endereço e segredo do aviso | Cifrados |
| Token do Chatwoot, chaves do S3, chave e segredo do bot | Cifrados; depois de gravados, só aparecem mascarados |
| Memória curta e sessões do bot | Cifradas |
| Mensagens esperando no agrupamento | Cifradas, em banco |
| Mensagens pendentes de aprovação | Conteúdo guardado só até a decisão ou o vencimento; decididas com mais de 14 dias são apagadas |
Nenhum desses segredos aparece em log, resposta, erro, tela da equipe ou aviso.
O que a ProxyBox guarda, e por quanto tempo?
| Dado | Tempo |
|---|---|
| Avisos entregues ou na fila (inclui o conteúdo do evento) | 7 dias; na consulta (/events), 7 dias |
| Registro de atividade (operação, resultado, tempo, 4 últimos dígitos do destino) | 30 dias; nunca o texto |
| Linha do tempo da instância (conexões, erros, trocas) | 90 dias |
| Sessão do número conectado | Enquanto a instância existir (veja a privacidade) |
| Lista de não perturbe, etiquetas, agendamentos pendentes | Até você remover |
| Mídia recebida | Não é guardada pela ProxyBox para você; vai ao seu bucket se você ligar o S3 |
O que não guardamos: o texto das mensagens no registro de atividade, a sua chave (só o hash) e chaves de terceiros em texto aberto.
O que a segurança da API não resolve?
- O WhatsApp pode bloquear o número. A API é não oficial, e nada aqui o evita; a ProxyBox não reembolsa por bloqueio. Veja os limites e erros.
- O seu receptor continua sendo seu. Se o seu sistema não confere a assinatura, qualquer um pode fingir um aviso.
- O conteúdo que você manda a bots e a modelos de IA vai para o serviço escolhido (OpenAI, Anthropic e outros), sob as regras dele.
- A IP dedicada não é anonimato. Ela mantém o número no mesmo lugar; não esconde nada de ninguém.
- Quem tem a chave envia mensagens em nome do número. Trate-a como uma senha.
Como reporto um problema?
Abra um ticket no painel ou escreva ao suporte descrevendo o que você viu, sem enviar chaves reais. Se achar uma falha de segurança, relate em particular antes de publicar; respondemos pelo canal do suporte.
Como limito a chave a IPs permitidos?
Resposta curta: com o ajuste api_allowlist você diz de quais IPs a chave da instância pode ser usada (até 20 IPs ou faixas CIDR, IPv4 ou IPv6). Quem chamar de outro lugar recebe 403 ip_not_allowed. Lista vazia libera qualquer IP. A regra vale na API v1 e também nas rotas no estilo da Evolution e da Z-API. O painel não é afetado.
Recurso em beta: pode mudar. A lista foi testada sem tráfego real. Um ponto de atenção está na seção sobre como o IP é lido, mais abaixo.
Por que restringir a chave?
A chave pbwa_… é a senha da instância: quem a tem envia mensagens do seu número. Mesmo guardada num cofre, ela passa por servidores, logs e máquinas de desenvolvedores. Limitar a chave aos IPs dos seus servidores faz com que um vazamento (um commit em repositório público, um print de tela, um log) não sirva para quem está fora. É a mesma ideia de um firewall, aplicada à chave.
Como configuro?
Com PUT /instance/settings, passando a lista em api_allowlist:
curl -X PUT "https://proxybox.com.br/api/whatsapp/v1/instance/settings" \
-H "apikey: SUA_CHAVE" -H "Content-Type: application/json" \
-d '{"api_allowlist": ["203.0.113.7", "198.51.100.0/24", "2001:db8::/32"]}'
Para remover a restrição, envie a lista vazia: {"api_allowlist": []}.
| Regra | Valor |
|---|---|
| Máximo de entradas | 20 |
| Formatos | IPv4, IPv6, ou faixa CIDR de qualquer um dos dois |
| Lista vazia | qualquer IP (padrão) |
| Onde vale | API v1, rotas no estilo da Evolution e rotas no estilo da Z-API |
| Onde não vale | O painel da ProxyBox (usa a sua sessão) |
Entradas mal formadas fazem a API recusar a lista inteira com 422 invalid_request e a indicação do campo.
Como a API me protege de me bloquear?
Ao gravar a lista pela API, o endereço de onde veio o pedido precisa estar nela. Se não estiver, a API recusa a gravação e a lista antiga continua valendo. No painel, ao lado do campo, aparece o IP atual do seu navegador, com um aviso, para você não salvar uma lista sem ele.
Se mesmo assim a lista errada for gravada (por exemplo, o servidor mudou de IP), entre no painel, abra os ajustes da instância e limpe ou corrija a lista: o painel não depende dela.
O que o cliente recebe quando está fora da lista?
{ "ok": false, "error": "ip_not_allowed", "message": "Este IP não está na lista de IPs permitidos da chave." }
HTTP 403. O erro vem antes de qualquer outra verificação da chave, e não conta como mensagem enviada. Na Z-API e na Evolution, o mesmo bloqueio devolve o erro no formato daquelas APIs, com o mesmo status.
Como o IP é descoberto?
A ProxyBox usa o cabeçalho CF-Connecting-IP quando ele traz um IP válido e, se não houver, o IP da conexão. Isso vale porque o site fica atrás da Cloudflare, que preenche o cabeçalho. Duas consequências práticas:
- se o seu servidor sai por NAT ou por um proxy, a lista deve ter o IP de saída dele, não o interno;
- a premissa é que a origem só aceite tráfego vindo da Cloudflare. Se algum dia a origem ficar exposta diretamente, o cabeçalho poderia ser forjado; isso é um limite conhecido, registrado nas notas da versão, e é uma razão para tratar a lista como uma camada a mais, não como a única proteção.
E os IPs de saída dos avisos?
É o caminho inverso: se o seu sistema só aceita conexões de endereços conhecidos, libere os IPs dos quais a ProxyBox envia os avisos. Hoje o endereço é 209.222.97.88. A lista oficial e atual fica no painel (em Avisos), em /api-whatsapp/status?format=json e no guia do aviso automático. Se o seu firewall bloquear esse endereço, os avisos vão falhar e entrar no ciclo de novas tentativas.
Em Python e em Node
import os, requests
r = requests.put(
"https://proxybox.com.br/api/whatsapp/v1/instance/settings",
headers={"apikey": os.environ["WA_KEY"]},
json={"api_allowlist": ["203.0.113.7"]},
timeout=30,
)
print(r.status_code, r.json())
const r = await fetch("https://proxybox.com.br/api/whatsapp/v1/instance/settings", {
method: "PUT",
headers: { apikey: process.env.WA_KEY, "Content-Type": "application/json" },
body: JSON.stringify({ api_allowlist: ["203.0.113.7", "198.51.100.0/24"] }),
});
console.log(r.status, await r.json());
O que acontece com ferramentas que usam a minha chave?
- n8n, Make, Zapier e outros serviços em nuvem saem por IPs que mudam ou que pertencem a muitos clientes. Se a lista só tiver o seu servidor, eles serão bloqueados. Veja o IP de saída do serviço na documentação dele, ou deixe a lista vazia nesses casos.
- O conector MCP roda no seu computador: o IP é o da sua rede.
- Bots e integrações da própria ProxyBox (Typebot, Dify, Chatwoot, S3) rodam por dentro e não usam a chave; a lista não os afeta.
Veja o resumo das camadas de proteção em segurança e a visão de quem pode fazer o quê em equipe e papéis.
Veja também
- Equipe, papéis e métricas da API de WhatsApp
- Webhook da API de WhatsApp: eventos e assinatura
- Guardar mídia do WhatsApp no S3, R2 ou MinIO
- Aprovação humana de mensagens da API de WhatsApp
Índice completo: documentação. Sobre o produto: API de WhatsApp por instância.
Autoria: equipe técnica da ProxyBox. Atualizado em 11/11/2026, contra o código e as notas técnicas da versão 1.2. Descrição do que foi construído; não é certificação.