Segurança da API do WhatsApp: como proteger token, webhook e dados do cliente

Três coisas decidem se a sua integração com a API do WhatsApp é segura: onde o token fica guardado, se você valida a origem do webhook antes de processar, e o que você faz com o conteúdo da mensagem depois de recebê-la. Nenhuma das três é complexa — e é exatamente por isso que costuma ficar para depois.

O token não é uma configuração, é uma credencial

A key da sua instância dá acesso total a ela: enviar mensagem, ler conversa, criar grupo. Trate como trataria a senha de um banco de dados de produção.

Onde ela não pode estar:

• Commitada num repositório, mesmo privado — repositórios vazam, e o histórico do git guarda tudo.
• No código de um app mobile ou de uma extensão de navegador. Qualquer binário distribuído pode ser descompilado.
• Chamada direto do frontend. Abra o DevTools de qualquer site que faça isso e a key está ali, na aba Network.
• Em log de aplicação. console.log(req.headers) em produção é uma forma comum de vazar credencial sem perceber.

Onde ela deve estar: variável de ambiente (.env, nunca versionado) ou um gerenciador de segredos (AWS Secrets Manager, Vault, variáveis do provedor de deploy). Se você entrega software para vários clientes, cada instância tem a própria key — uma vazada não compromete as outras, e você consegue revogar uma sem afetar o resto da base.

// Errado: hardcoded no código
const WAME_KEY = "abc123";

// Certo: variável de ambiente
const WAME_KEY = process.env.WAME_KEY;

Validar que o webhook é de verdade

Seu endpoint de webhook é uma URL pública. Sem validação, qualquer um que descubra a URL pode mandar um payload forjado — uma "mensagem" que nunca chegou de verdade, tentando fazer seu bot executar uma ação.

A defesa é a assinatura HMAC no header X-Hub-Signature-256, no mesmo padrão da Meta Cloud API: o corpo é assinado com um secret que só você e a plataforma conhecem.

import crypto from "crypto";

function assinaturaValida(corpoRaw, assinaturaRecebida, secret) {
  const esperada = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(corpoRaw)
    .digest("hex");

  // timingSafeEqual evita vazar informação por tempo de comparação
  return crypto.timingSafeEqual(
    Buffer.from(esperada),
    Buffer.from(assinaturaRecebida)
  );
}

app.post("/webhook/wame", express.raw({ type: "application/json" }), (req, res) => {
  const assinatura = req.headers["x-hub-signature-256"];

  if (!assinatura || !assinaturaValida(req.body, assinatura, process.env.WEBHOOK_SECRET)) {
    return res.sendStatus(401); // descarta sem processar
  }

  res.sendStatus(200);
  processar(JSON.parse(req.body));
});

Repare que a validação precisa do corpo bruto da requisição — se um middleware já converteu para JSON antes desse ponto, o hash não bate. É por isso que o exemplo usa express.raw() nessa rota específica, em vez do express.json() global.

Idempotência é segurança, não só robustez

Um mesmo evento pode chegar duas vezes — reentrega de rede, retry do provedor. Sem controle, isso vira desde mensagem duplicada até uma automação de cobrança disparando duas vezes para o mesmo pedido.

const processados = new Set(); // em produção: Redis com TTL

function jaProcessado(messageId) {
  if (processados.has(messageId)) return true;
  processados.add(messageId);
  return false;
}

O tratamento completo de reentrega, ordem de eventos e retry com backoff está em webhook em produção: assinatura, retry e idempotência — este artigo foca na assinatura como controle de acesso; aquele foca na confiabilidade sob volume.

O que não logar

Mensagem de WhatsApp costuma carregar dado pessoal — nome, endereço, às vezes CPF ou informação de saúde num atendimento. Duas práticas comuns viram passivo:

• Logar o corpo da mensagem em texto puro num sistema de log que qualquer pessoa do time acessa. Prefira logar messageId e metadados (canal, timestamp), não o conteúdo.
• Guardar histórico de conversa sem prazo de retenção definido. Se não existe uma política de por quanto tempo aquilo fica armazenado, na prática é "para sempre" — e isso é uma decisão que deveria ser explícita, não um efeito colateral.

Quem entrega WhatsApp integrado ao sistema de um cliente também vira operador desses dados perante a LGPD, com obrigações específicas de contrato — isso está detalhado em API de WhatsApp e LGPD: o que garantir no contrato.

Checklist rápido

Conclusão

Segurança na API do WhatsApp não é um projeto à parte — é uma consequência de tratar a key como credencial, validar a origem de cada webhook antes de agir sobre ele e ser deliberado sobre o que fica guardado e por quanto tempo. Nenhum desses pontos exige infraestrutura sofisticada; exige apenas não pular a etapa. Se o seu bot ainda responde a qualquer payload que chega na URL do webhook, esse é o primeiro ponto a fechar.