Raphael Serafim· Publicado em 10 de setembro de 2026· 9 min de leitura

Webhook do WhatsApp não chega: as 7 causas e como testar em 30 segundos

O webhook da API do WhatsApp não está chegando no seu servidor. Antes de mexer no código, um teste com webhook.site diz de que lado está o problema. As 7 causas mais comuns, na ordem em que vale investigar.

Ver como Markdown

Antes de abrir o código, descubra de que lado está o problema. Isso leva 30 segundos e economiza a tarde inteira — porque "o webhook não chega" tem duas causas completamente diferentes, e depurar a errada não leva a lugar nenhum.

O teste dos 30 segundos

Abra o webhook.site. Ele gera uma URL única na hora, sem cadastro.
Copie essa URL.
Configure-a como webhook da sua instância, no painel ou pela API.
Mande uma mensagem qualquer para o número conectado.
Olhe a tela do webhook.site.

Se o evento apareceu lá: a plataforma está enviando certo. O problema é o seu servidor — pule para as causas 4 a 7.

Se não apareceu: o evento não está saindo. O problema é a configuração da instância — causas 1 a 3.

O webhook.site ainda mostra o corpo exato que chega, com os headers. É a forma mais rápida de conferir o formato antes de escrever qualquer parser — e você pode copiar aquele JSON real para usar nos seus testes.

Causa 1 — A URL não é HTTPS válido

A mais comum e a mais chata de descobrir, porque falha em silêncio.

http:// sem TLS: recusado.
HTTPS com certificado autoassinado: recusado.
HTTPS com certificado vencido: recusado.
Certificado válido só para o domínio sem www, e a URL cadastrada com www: recusado.

Não há erro do seu lado. Simplesmente não chega nada.

Como conferir sem sair do terminal:

curl -sS -o /dev/null -w "%{http_code}\n" https://seu-dominio.com/webhook/wame

Se der erro de certificado aqui, dará lá também.

Causa 2 — A instância está desconectada

Instância caída não emite evento. Parece óbvio, mas é a segunda causa mais frequente — especialmente na API não oficial, em que a sessão pode cair sozinha.

curl "https://us.api-wa.me/SUA_KEY/instance"

Se o status não for conectado, o webhook é consequência, não a causa. Reconecte primeiro.

Causa 3 — Filtro de evento ou formato errado

A WAME permite filtrar quais eventos a instância envia e em qual formato. Duas armadilhas:

Formato. Se a sua instância está no formato meta e o seu código espera o formato antigo (ou vice-versa), o evento chega e o parser não encontra nada. O formato meta é o envelope padrão da Cloud API e é o recomendado — é ele que faz o mesmo handler servir WhatsApp, Instagram e Messenger.

Filtro. Se só alguns eventos estão habilitados, mensagem recebida pode simplesmente não estar na lista.

Confira as duas coisas no painel da instância antes de suspeitar do código.

Causa 4 — Você está lendo o campo errado

Chegou no webhook.site mas o seu código não vê nada? Provavelmente é isto.

No envelope da Meta, mensagem e status de entrega vivem em campos diferentes:

{
  "entry": [{
    "changes": [{
      "value": {
        "messages":  [ /* mensagem recebida */ ],
        "statuses":  [ /* entregue, lida, falhou */ ]
      }
    }]
  }]
}

O evento de status não tem messages. Código que faz value.messages[0] direto quebra — ou, pior, não quebra e simplesmente ignora tudo:

// errado: status de entrega derruba ou passa batido
const msg = body.entry[0].changes[0].value.messages[0];

// certo
const value = body?.entry?.[0]?.changes?.[0]?.value;
const msg = value?.messages?.[0];
if (!msg) return res.sendStatus(200);   // era status, não mensagem

Vale a mesma guarda para msg.type: áudio, imagem e documento não têm text.body.

Causa 5 — Seu servidor não responde 200 rápido

Se o webhook chega duplicado, é isto. A plataforma espera confirmação; sem ela, reenvia.

O erro clássico é processar antes de responder:

// errado: o cliente recebe a resposta 2 ou 3 vezes
app.post('/webhook/wame', async (req, res) => {
  await chamarIA(req.body);        // 3 segundos
  await salvarNoBanco(req.body);   // mais 1
  res.sendStatus(200);             // tarde demais
});

// certo
app.post('/webhook/wame', (req, res) => {
  res.sendStatus(200);             // primeiro isto
  processar(req.body).catch(console.error);
});

Se o seu processamento é pesado, coloque numa fila e responda 200 assim que enfileirar. Vale ler também sobre idempotência e retry em produção: responder rápido resolve a duplicata na origem, mas tratar o messageId como chave única é o que garante que uma duplicata que passe não vire mensagem dobrada para o cliente.

Causa 6 — O corpo não está sendo parseado

Em Express, sem express.json() o req.body chega undefined e parece que o webhook não chegou:

app.use(express.json());   // antes das rotas

Se você valida assinatura, precisa do corpo cru também — e express.json() sozinho não guarda o original:

app.use(express.json({
  verify: (req, _res, buf) => { req.rawBody = buf; },
}));

Causa 7 — Firewall, proxy ou WAF barrando

Se o webhook.site recebe e o seu servidor não, e as causas acima estão descartadas, algo no meio está bloqueando: regra de firewall, Cloudflare em modo agressivo, WAF recusando POST de origem desconhecida, ou um proxy exigindo autenticação.

Teste enviando um POST de fora, simulando a plataforma:

curl -X POST https://seu-dominio.com/webhook/wame \
  -H "Content-Type: application/json" \
  -d '{"object":"wame","provider":"whatsapp","entry":[{"changes":[{"value":{"messages":[{"from":"5566996852025","type":"text","text":{"body":"teste"}}]}}]}]}' \
  -i

Se isso não chegar ao seu handler, o problema está na infraestrutura e não na aplicação.

A ordem que economiza tempo

Testar com o webhook.site — decide o lado.
Se não chegou lá: HTTPS, instância conectada, filtro/formato.
Se chegou lá: campo certo, 200 rápido, parser do corpo, firewall.

Quase todo caso cai numa dessas sete. Perseguir na ordem evita o cenário mais comum de todos: passar duas horas revisando o parser quando a instância estava desconectada.

Depois que voltar a funcionar

Webhook que chega não é o mesmo que webhook confiável. Antes de colocar carga em cima, veja o que muda em produção — assinatura, reentrega e mensagem processada duas vezes.

E se você ainda está montando a integração, o guia dos endpoints essenciais e o primeiro envio nos três canais cobrem o outro lado do fluxo.

Pronto para automatizar seu WhatsApp?

Crie sua conta gratuita e comece a enviar mensagens pela API em minutos.

Começar grátis

Perguntas frequentes

Como testar se o webhook do WhatsApp está sendo enviado?+

Abra webhook.site, copie a URL única que ele gera, configure-a como webhook da sua instância e mande uma mensagem para o número. Se o evento aparecer na tela do webhook.site, a plataforma está enviando corretamente e o problema está no seu servidor. Se não aparecer, o problema é a configuração da instância.

Por que meu webhook recebe status de entrega mas não mensagens?+

Quase sempre é filtro de evento. A instância pode estar configurada para enviar apenas alguns tipos de evento, ou o seu código está lendo o campo errado do envelope. Mensagens de texto chegam em entry[0].changes[0].value.messages[0]; status de entrega chegam em value.statuses, e é comum o código tratar os dois como se fossem o mesmo.

O webhook chega duplicado. Por quê?+

Porque o seu endpoint demorou a responder 200. Toda plataforma de webhook reenvia quando não recebe confirmação rápida. A correção é responder 200 imediatamente e processar depois, de forma assíncrona — nunca deixar o processamento pesado antes da resposta.

O webhook funciona em localhost?+

Não diretamente: a plataforma precisa alcançar a sua URL pela internet. Em desenvolvimento use ngrok, cloudflared ou similar para expor a porta local com uma URL pública HTTPS, e configure essa URL como webhook.

Preciso de HTTPS no webhook?+

Sim, com certificado válido. URL http:// simples ou HTTPS com certificado autoassinado ou vencido é recusada silenciosamente — o envio falha e não há erro visível do seu lado, o que faz esta ser uma das causas mais demoradas de descobrir.