---
title: "Webhook do WhatsApp não chega: as 7 causas e como testar em 30 segundos"
description: "O webhook da API do WhatsApp não está chegando no seu servidor. Um teste com webhook.site diz de que lado está o problema. As 7 causas mais comuns, em ordem."
url: "https://wame.api.br/blog/webhook-whatsapp-nao-chega-como-testar"
language: "pt-BR"
og:type: "article"
published_time: "2026-09-10"
modified_time: "2026-09-10"
author: "Raphael Serafim"
keywords: "webhook whatsapp não chega, webhook whatsapp não funciona, testar webhook whatsapp, webhook api whatsapp, webhook não recebe mensagem, debug webhook whatsapp, webhook.site whatsapp"
reading_time: "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. Um teste com webhook.site diz de que lado está o problema. As 7 causas mais comuns, em ordem.

**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

1. Abra o [webhook.site](https://webhook.site). Ele gera uma URL única na hora, sem cadastro.
2. Copie essa URL.
3. Configure-a como webhook da sua instância, no painel ou pela API.
4. Mande uma mensagem qualquer para o número conectado.
5. 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:

```bash
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.

```bash
curl "https://server.wame.api.br/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](/blog/webhook-whatsapp-instagram-messenger-padrao-meta) 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:

```json
{
  "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:

```js
// 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:

```js
// 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](/blog/webhook-producao-assinatura-retry-idempotencia): 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:

```js
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:

```js
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:

```bash
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

1. Testar com o **webhook.site** — decide o lado.
2. Se não chegou lá: **HTTPS**, **instância conectada**, **filtro/formato**.
3. 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](/blog/webhook-producao-assinatura-retry-idempotencia) — assinatura, reentrega e mensagem processada duas vezes.

E se você ainda está montando a integração, o [guia dos endpoints essenciais](/blog/guia-api-whatsapp-endpoints) e o [primeiro envio nos três canais](/blog/wame-api-primeiro-envio-whatsapp-instagram-messenger) cobrem o outro lado do fluxo.

## 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.