← Blog3 de julho de 2026

Como proteger a chave da sua API de WhatsApp

A chave da sua API de WhatsApp é uma senha com poderes específicos: quem a tem consegue enviar mensagem em nome da sua empresa, para qualquer número, quantas vezes o limite permitir. Não é só uma questão de custo — é a sua reputação saindo pelo canal errado.

E o vazamento de chave é, disparado, o incidente de segurança mais comum em integração de WhatsApp. Quase sempre pelo mesmo punhado de erros. Este guia cobre onde a chave deve morar, os lugares onde ela nunca deve aparecer, e o que fazer nos primeiros minutos depois de um vazamento.

O que alguém com a sua chave consegue fazer

Vale ser concreto sobre o risco antes de falar de prevenção:

Enviar mensagem para qualquer número usando as suas instâncias, com o seu número como remetente.
Consumir o seu limite de requisições, fazendo os seus envios legítimos falharem com 429.
Queimar o seu número. Este é o pior. Um terceiro disparando spam pelo seu número leva a denúncias e ao bloqueio pela Meta — e recuperar número bloqueado não é um processo com prazo.

Repare que o dano não é proporcional ao valor da assinatura. Perder o número que atende os seus clientes custa muito mais do que a mensalidade.

Onde a chave deve morar

Em variável de ambiente. Sempre. Nunca em código, nunca em arquivo versionado, nunca em constante no topo do arquivo.

// certo
const chave = process.env.ZAPIXO_API_KEY;

// errado — vai para o Git e fica no histórico para sempre
const chave = "zpx_a1b2c3d4e5f6...";

Em produção, a chave vem do painel do seu provedor de hospedagem. Em desenvolvimento, de um .env.local que está no .gitignore.

Antes de qualquer coisa, confirme que o arquivo de ambiente está mesmo ignorado:

git check-ignore -v .env.local

Se o comando não devolver nada, o arquivo não está ignorado — e provavelmente já foi commitado.

Os cinco lugares onde a chave vaza

1. No repositório

O clássico. Alguém comita o .env "só para o colega testar" e o repositório vira público seis meses depois. Vale procurar no histórico, não só nos arquivos atuais:

git log -p --all -S "zpx_" | head -40

Se aparecer, a chave está comprometida mesmo que você a apague hoje: o histórico do Git guarda tudo, e qualquer clone antigo continua com ela.

2. No front-end

Este é o erro mais grave e o menos percebido. Chamar a API de WhatsApp direto do navegador significa entregar a chave para todo visitante do site — basta abrir as ferramentas de desenvolvedor.

// NUNCA faça isso em código que roda no navegador
fetch("https://zapixo.com.br/api/v1/messages/text", {
  headers: { Authorization: "Bearer zpx_..." },
});

A regra é simples: a API de WhatsApp é chamada do servidor, sempre. Se o front precisa disparar uma mensagem, ele chama o seu backend, e o seu backend chama a API. O mesmo vale para aplicativo mobile: código distribuído para o usuário pode ser inspecionado, então chave embutida em app é chave pública.

Em ferramentas no-code, o cuidado é equivalente — a chave vai nos parâmetros privados do plugin ou na configuração do servidor, nunca em um campo que o navegador enxerga.

3. Em log e mensagem de erro

Registrar a requisição inteira parece útil até o dia em que o log vaza:

// vaza a chave no log
console.error("falhou:", { url, headers, body });

// registra o que interessa, sem o header de autorização
console.error("falhou:", { url, status: res.status, body });

O mesmo vale para relatório de erro automático, que costuma capturar cabeçalhos por padrão. Configure a ferramenta para mascarar o Authorization.

4. Em captura de tela e em conversa

Chave aparece em screenshot de painel colada em grupo de suporte, em vídeo de treinamento e em mensagem para o desenvolvedor freelancer. Trate a chave como trata uma senha: ela não passa por chat.

5. Em ferramenta de terceiro

Toda plataforma no-code, todo painel de automação e todo colaborador externo que recebe a chave é mais uma cópia dela existindo no mundo. Não é motivo para não usar — é motivo para usar uma chave separada por integração.

Uma chave por integração

Se você usa uma chave só para tudo, qualquer suspeita de vazamento obriga a revogar e reconfigurar todos os sistemas de uma vez, no susto.

Com uma chave por integração — uma para o site, outra para o n8n, outra para o ERP, outra para cada cliente se você é agência — o vazamento fica contido: revoga aquela, reconfigura só aquele sistema, o resto continua funcionando.

Há um ganho técnico junto: o limite de 60 requisições por minuto é por chave. Compartilhar uma chave entre sistemas faz um consumir a cota do outro. O tratamento correto disso está em rate limit e fila, e o desenho para vários clientes em múltiplas instâncias.

Como saber se a chave está sendo usada

Duas fontes de sinal, e as duas valem uma olhada semanal.

A data de último uso. O painel registra quando cada chave foi usada pela última vez. Uma chave que você criou para um teste em março e aparece com uso ontem merece investigação imediata.

O volume de envio. Pico fora do padrão — madrugada, fim de semana, dobro do normal — é o sinal mais confiável de uso indevido. Se você tem um painel de fila, um alerta simples de "envios por hora acima do normal" pega isso antes do prejuízo.

Vale saber como a chave é guardada do outro lado: no Zapixo, ela é armazenada como hash, não em texto — nem a plataforma consegue recuperá-la depois de criada. Por isso a chave é exibida uma única vez, no momento da criação. Se você perdeu, não existe "ver de novo": gere outra e revogue a anterior.

O que fazer quando vazar

Ordem importa. Nos primeiros minutos:

Revogue a chave no painel. Primeiro passo, antes de investigar qualquer coisa. Chave revogada para de funcionar na hora, e toda requisição com ela passa a receber 401.
Gere uma nova e atualize o sistema afetado.
Verifique o que foi enviado enquanto a chave esteve exposta. O log de mensagens mostra o que saiu — se houver envio que você não reconhece, o problema é maior que a chave.
Cheque o status da instância. Uso abusivo por terceiro pode ter levado a bloqueio; o procedimento está em instância desconectou.
Só então descubra a origem. Repositório, log, ferramenta de terceiro, ex-colaborador.

Uma armadilha na hora do susto: código que trata 401 como erro temporário. Se a sua fila retenta indefinidamente com a chave revogada, ela gera milhares de requisições inúteis. 401 deve parar tudo e alertar, nunca entrar em laço de retentativa.

E se a chave vazou junto com dado de cliente — log com conversas, por exemplo —, aí não é só incidente técnico: pode haver dever de comunicação sob a LGPD. O que fazer está em LGPD em automação de WhatsApp.

Além da chave: o webhook também é uma porta

A URL de webhook que recebe as suas mensagens é pública por definição — qualquer um que descobrir o endereço pode mandar um POST para ele. Se o seu código confia no que chega sem verificar, alguém pode inventar mensagens que nunca existiram.

Três defesas, em ordem de esforço:

URL imprevisível. /webhooks/wh_8f3a9c2e1b7d é bem melhor que /webhooks/whatsapp.
Segredo compartilhado na URL ou em cabeçalho, conferido antes de processar.
Validação do formato antes de confiar em qualquer campo do payload.

O tratamento correto do recebimento está em webhook de WhatsApp.

Checklist

O último item é o mais esquecido e o que mais atrasa resposta a incidente. Se só você sabe onde revogar, o vazamento que acontece nas suas férias fica ativo por duas semanas.

Resumo

Chave de API de WhatsApp é senha com poder de falar em nome da sua empresa. Ela mora em variável de ambiente, é usada só do servidor, aparece separada por integração e é revogável em segundos por mais de uma pessoa.

O maior risco não é técnico, é de reputação: quem tem a sua chave manda mensagem com o seu número. Revogar leva dez segundos; recuperar um número bloqueado, não tem prazo. A referência dos endpoints e dos códigos de retorno está na documentação.