WhatsApp Cloud com webhook manual do Painel de Apps da Meta

Abrir em

Ver como Markdown

Abrir no ChatGPT Abrir no Claude

Ramon Duarte

Última atualização em 4 de ago de 2026

Visão geral

Além do Embedded Signup (login guiado da Meta), o canal WhatsApp Cloud também pode ser conectado no modo manual: você informa as credenciais do seu próprio app Meta (API key, Phone Number ID e Business Account ID) e configura o webhook diretamente no Painel de Apps da Meta (WhatsApp → Configuração → Webhook). Esse modo é ideal para quem já tem um app Meta próprio, precisa de controle total sobre as assinaturas de webhook ou usa um token com permissões limitadas.

A plataforma oferece uma única URL de callback em nível de app que atende todos os seus números e contas WhatsApp Business (WABAs): cada evento é roteado automaticamente pelo conteúdo do payload. Também há uma URL alternativa por número, se preferir configurar número a número.

Pré-requisitos

Perfil de administrador na plataforma.
Um app Meta com o produto WhatsApp habilitado e acesso ao Painel de Apps.
API key (token de acesso permanente), Phone Number ID e Business Account ID do número.
Opcional, mas recomendado: o App Secret do app Meta (Configurações do app → Básico), usado para validar a assinatura X-Hub-Signature-256 de cada webhook recebido.

Passo a passo

Em Configurações → Caixas de Entrada, crie uma nova caixa e escolha WhatsApp.
Selecione o provedor WhatsApp Cloud (modo manual, sem o login da Meta).
Preencha nome da caixa, número de telefone, Phone Number ID, Business Account ID e API key.
(Recomendado) Informe o App Secret para ativar a verificação de assinatura dos webhooks.
Escolha se a plataforma deve registrar o webhook automaticamente via Graph API. Desative essa opção se você prefere configurar o webhook manualmente no Painel de Apps da Meta.
Ao criar a caixa, a tela exibe a URL de callback (nível de app e por número) e o token de verificação, com botões de copiar.
No Painel de Apps da Meta, abra WhatsApp → Configuração → Webhook, cole a URL de callback e o token de verificação e clique em Verificar e salvar.
Assine os campos de webhook: no mínimo messages; recomendamos assinar também os campos de templates, qualidade do número, conta e segurança para receber os eventos administrativos em tempo real.
Envie uma mensagem de teste para o número e confirme que ela chega na caixa de entrada.

Configurações & opções

Aba Saúde da Conta (Configurações da caixa → Saúde da conta): mostra o painel de configuração manual do webhook com a URL, o token (mascarado, com revelar/copiar), o status do registro, o estado da verificação de assinatura (HMAC) e o modo de registro (automático ou manual).
Reassinar: refaz o registro do webhook via Graph API (disponível quando o registro automático está ativo).
Rotacionar token: gera um novo token de verificação. No modo manual, cole o novo valor no Painel de Apps da Meta depois de rotacionar.
Eventos recentes da conta: a mesma aba lista os últimos eventos administrativos recebidos — status de templates, qualidade do número, alertas de conta, capacidade do negócio e segurança — com selos de severidade.

Casos de uso

Empresas com app Meta próprio que não querem (ou não podem) usar o Embedded Signup.
Operações com múltiplos números e WABAs no mesmo app Meta: uma única URL de callback atende todos; os lotes de eventos com várias entradas são processados por completo.
Tokens com permissões limitadas (sem whatsapp_business_management): com o registro automático desativado, a plataforma nunca chama as APIs de assinatura da Meta.

Dicas, limites e boas práticas

Configure sempre o App Secret: sem ele, os webhooks são aceitos sem verificação de assinatura (a plataforma registra um aviso em log). O operador da instalação pode exigir assinatura em todas as caixas de forma global.
Assine os campos de templates e qualidade no Painel de Apps: os status de templates (aprovado/rejeitado/pausado) passam a refletir na plataforma em tempo real, sem esperar a sincronização periódica.
Se o Painel da Meta rejeitar algum campo de webhook, salve com um conjunto menor — o mínimo indispensável é messages.
Ao rotacionar o token com o registro automático desativado, lembre de atualizar o valor no Painel de Apps da Meta, senão a verificação do webhook falha na próxima validação.

Solução de problemas

"Verificar e salvar" falha na Meta: confira se a URL de callback foi copiada por completo e se o token de verificação é exatamente o exibido na plataforma (sem espaços).
Mensagens não chegam: confirme que o campo messages está assinado no Painel de Apps e que o número não está listado como inativo pela operação.
Webhook marcado como divergente na aba Saúde da Conta: a URL registrada na Meta é diferente da esperada — use Reassinar (registro automático) ou corrija a URL manualmente no Painel de Apps.
Eventos administrativos não aparecem: os campos correspondentes (templates, qualidade, conta, segurança) precisam estar assinados no webhook do app Meta.