Empresa brasileira · Entrega automática · Suporte em português Seg a sex, 9h as 18h · PIX em reais
ProxyBox
API de WhatsApp · Avisos e controle

Segurança da API de WhatsApp: como protegemos a chave, o aviso e os seus dados

Como a chave, os IPs permitidos, os avisos assinados e os segredos cifrados são tratados, o que é guardado, por quanto tempo, e o que a API não resolve.

11 min de leitura Atualizado em 14 de novembro de 2026
Resposta curta
A chave pbwa_… abre uma instância e só o hash dela fica guardado; os avisos saem assinados (HMAC-SHA256); endereços de terceiros (avisos, bots, Chatwoot, S3) passam por uma guarda de rede que bloqueia endereços internos; segredos são cifrados; e o registro de atividade nunca guarda o texto das mensagens. Você pode restringir a chave a IPs permitidos e dar acesso à equipe por papéis, sem compartilhar a chave. Uma seção própria explica como limitar a chave a até 20 IPs permitidos (api_allowlist, erro 403 ip_not_allowed).

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 nova no 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átis

Como 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:

bash
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?

json
{ "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

python
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())
js
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

Í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.

Perguntas frequentes

A ProxyBox consegue ler a minha chave?
Não. Guardamos apenas o hash da chave e os quatro últimos caracteres, para você reconhecê-la. Se perder, gere outra; a anterior para de funcionar na hora.
Existe uma chave mestra que abre todas as instâncias?
Não. A chave abre uma instância só. Não existe chave global da conta no acesso à API de WhatsApp.
A API é segura contra bloqueio do número?
Segurança da API e risco de bloqueio do WhatsApp são coisas diferentes. A API protege o acesso e os dados; o bloqueio depende do comportamento do número, e nada aqui o evita.
Se eu errar a lista, fico sem acesso?
Ao salvar pela API, a lista que deixaria de fora o IP de quem está pedindo é recusada. E o painel (que usa a sua sessão e não a chave) nunca é afetado: de lá você pode limpar a lista.
Lista vazia bloqueia tudo?
Não. Lista vazia significa qualquer IP, que é o padrão.
Servidor com IPv6?
Aceita. A lista aceita IPv4 e IPv6, individuais ou em faixa CIDR.

Guias relacionados

Pronto para colocar no ar?

Comece no sandbox, grátis. Quando funcionar, contrate a instância do seu número e pague com PIX ou saldo.

Com IP brasileiro dedicado R$ 89,90/mês
Só a instância (traga o seu IP) R$ 39,90/mês
Travou em alguma etapa?Manda o print do erro no WhatsApp. Respondemos em português.
Suporte em português Fale no WhatsApp