Skip to main content
Há três segredos e cada um se troca de um jeito. O token da instância não tem período de convivência; as API keys e o segredo do webhook têm, então planeje a troca com isso em mente.

​
Roteiro para um token vazado

1

Gere o token novo

No painel, em Credenciais da instância, clique em Gerar novo token e confirme. A partir desse instante, requisições com o token antigo recebem 401 instance_not_found.
2

Atualize as integrações

Troque o valor em todos os sistemas que usam a instância. Se você guarda a URL completa (com o token) em ferramentas no-code, a troca dá mais trabalho. Prefira guardar instance_id e token separados.
3

Confira os logs de webhook e a fila

Um token vazado pode ter sido usado para enviar mensagens. Veja GET /queue (e limpe com DELETE /queue se houver envios estranhos) e os Logs de webhook no painel.
4

Exija API key e restrinja os IPs

Ligue Exigir API key nas rotas de instância e, se os envios saem de IPs fixos, a allowlist. Assim uma URL vazada sozinha não basta.
A rotação do token da instância não desconecta o número nem mexe na fila. A sessão do WhatsApp continua ativa.

​
Troca de API key sem downtime

Como o workspace pode ter várias keys ativas ao mesmo tempo, a troca não exige desligar nada:
1

Crie a key nova

Em Segurança › API keys, clique em Nova API key e marque as mesmas permissões da que será trocada. O valor aparece uma vez; copie para o cofre de segredos.
2

Publique nas integrações

Troque o valor em Authorization: Bearer (ou no header Client-Token, se é assim que a integração envia). As duas keys funcionam enquanto você faz o deploy. Na lista, o último uso ajuda a ver se a antiga ainda recebe chamadas.
3

Revogue a antiga

Revogar corta a key na hora: chamadas com ela passam a receber 401 api_key_required. As outras keys não são afetadas.
Se a key vazou, inverta a ordem quando o risco justificar. Revogue primeiro e aceite a indisponibilidade até publicar a nova. Uma key com instances:read expõe o token de todas as instâncias, então gere também novos tokens (POST /account/instances/{id}/rotate-token ou pelo painel). Com webhooks:read, troque também o secret do workspace.
Com Exigir API key nas rotas de instância ligado, o painel não deixa revogar a última key com instances:operate. Criando a nova antes, como no roteiro acima, isso nunca acontece.

​
Troca do segredo do webhook sem perder entregas

  1. Chame POST /webhooks/secret; guarde o novo secret.
  2. Faça o seu endpoint aceitar os dois segredos por algumas horas (o suficiente para a última tentativa de reenvio, que acontece 6 h depois da primeira falha).
  3. Remova o antigo.

​
Desconectar de vez

Se o número em si foi comprometido (celular perdido, por exemplo), use POST /disconnect para encerrar a sessão do WhatsApp. A instância volta para qr e nada pode ser enviado até uma nova leitura. No celular, confira Aparelhos conectados e remova sessões desconhecidas.