Webhook: GET, POST e troca efetiva

GET e POST são verificações diferentes

GET: usado pela Meta para confirmar que você controla a URL. O endpoint deve devolver exatamente o valor de hub.challenge quando o verify token for válido.

POST: usado para entregar mensagens, status e eventos. O endpoint deve aceitar JSON e responder rapidamente com HTTP 2xx.

Conexão inicial com webhook próprio: política 3 × 5

Quando o assinante informa uma URL própria durante uma nova conexão, falhas relacionadas ao callback não ficam sendo repetidas por vários minutos.

Requisitos da URL antes do onboarding

• use uma URL HTTPS completa, pública e sem credenciais embutidas;
• não use localhost, hostname interno, IP privado ou domínio reservado;
• publique a rota antes de abrir o Embedded Signup;
• libere o GET de verificação de login, firewall e Cloudflare Access;
• valide o verify token no código e devolva apenas hub.challenge;
• mantenha DNS público e certificado TLS válidos;
• aceite POSTs e responda rapidamente com HTTP 2xx.

Fluxo completo

1. A Meta chama a URL por GET.
2. Seu servidor valida hub.verify_token.
3. Seu servidor devolve somente hub.challenge.
4. O Flow aplica a rota no nível seguro para a conexão.
5. O Flow relê a configuração do Phone Number ID.
6. A Meta entrega eventos por POST.
7. Seu sistema responde 2xx e processa de forma assíncrona.

Entrega direta da Meta ao seu endpoint

Com a rota própria confirmada, a Meta entrega os eventos operacionais compatíveis diretamente ao webhook configurado. A HookCloud aplica e verifica a rota, mas não atua como proxy do conteúdo normal das conversas.

Meta WhatsApp Cloud API
        ↓
Seu webhook HTTPS
        ↓
Seu CRM, n8n, Make ou backend

Eventos administrativos que não aceitam override podem continuar no callback do aplicativo HookCloud para observabilidade. Para arquitetura completa, assinatura, retries, Click-to-WhatsApp, BSUID e envio pela Graph API, consulte CRM próprio e integração técnica →

Exemplo Node.js / Express

app.get('/webhook', (req, res) => {
  const mode = req.query['hub.mode'];
  const token = req.query['hub.verify_token'];
  const challenge = req.query['hub.challenge'];
  if (mode === 'subscribe' && token === process.env.VERIFY_TOKEN) {
    return res.status(200).send(String(challenge));
  }
  return res.sendStatus(403);
});

app.post('/webhook', express.json({ limit: '2mb' }), (req, res) => {
  res.sendStatus(200); // confirme primeiro
  queueWebhook(req.body); // processe depois
});

Assinatura, corpo bruto e idempotência

• O corpo e os headers operacionais chegam diretamente da Meta, sem transformação da HookCloud.
• Capture o corpo bruto antes do parse caso utilize X-Hub-Signature-256.
• O verify token protege o GET, não substitui a assinatura do POST.
• O App Secret da HookCloud não é compartilhado; portanto, a validação HMAC independente não é oferecida no modo direto.
• Responda HTTP 2xx rapidamente e use messages[].id para idempotência.

Usernames, BSUID e telefone opcional

Seu webhook não deve depender somente de from ou wa_id. Em cenários compatíveis com usernames, a Meta pode fornecer um BSUID mesmo quando o telefone não estiver presente.

Ver checklist de prontidão BSUID →

Botões relacionados ao webhook

Teste de alcance da CláudIA

Quando a dúvida do atendimento privado é sobre callback, a CláudIA pode fazer um teste controlado e somente leitura da URL pública associada à conexão.

Trocar o webhook com segurança

Tempo de operação e cronômetro

Na conexão inicial por webhook próprio, o painel mostra uma estimativa regressiva de aproximadamente 00:45 e informa que serão feitas no máximo três tentativas, com intervalo mínimo de cinco segundos. A duração real pode ganhar alguns segundos conforme a frequência do worker e o tempo de resposta da Meta.

Alteração de webhook, verificação de Chatwoot, transferência e desconexão continuam usando seus próprios fluxos e estimativas.

Limpeza segura da tentativa incompleta

Alteração durante transferência/onboarding

Se a conexão estiver sendo transferida ou ainda não tiver WABA acessível, o Flow mantém a operação em espera ou encerra com orientação de reconexão. Não força uma escrita remota incerta. O log deve indicar Aguardando conclusão da conexão com a Meta ou Refaça a conexão.

WABA com vários números

Quando vários números compartilham a WABA, a alteração de uma conexão prioriza o callback específico do Phone Number ID. O callback geral da WABA pode ser preservado para não redirecionar os outros números.

Erros comuns do callback próprio

Abrir o catálogo completo de erros em português →

Webhook próprio x entrega externa gerenciada

• A verificação manual faz uma leitura; a automática tenta no máximo três vezes.
• A verificação passiva não bloqueia Configurar caixa existente, Usar webhook próprio ou Desconectar.
• Uma URL própria antiga não é aceita como Chatwoot apenas por ser externa.
• O webhook global da HookCloud é fallback do App, não o webhook personalizado do cliente.

Trocar Chatwoot por webhook próprio

1. Pare envios e automações da inbox antiga; preserve a caixa se precisar manter o histórico.
2. No card do Flow, clique Usar webhook próprio.
3. Informe a URL e aguarde o readback terminal.
4. Faça um teste real de POST e confirme que apenas o destino novo recebe as mensagens.

Ver o procedimento completo.