--- title: "Webhook do WhatsApp não chega? 7 causas e como testar" description: "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." url: "https://api-wa.me/blog/webhook-whatsapp-nao-chega-como-testar" language: "pt-BR" og:type: "article" og:site_name: "WAME API" --- [Início](https://api-wa.me/)/[Blog da API do WhatsApp](https://api-wa.me/blog)/Webhook do WhatsApp não chega: as 7 causas e como testar em 30 segundos Raphael Serafim· Publicado em 10 de setembro de 2026· 9 min de leitura Compartilhar # 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. Copiar para LLM[Ver como Markdown](https://api-wa.me/blog/webhook-whatsapp-nao-chega-como-testar.md) **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://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](https://api-wa.me/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](https://api-wa.me/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](https://api-wa.me/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](https://api-wa.me/blog/guia-api-whatsapp-endpoints) e o [primeiro envio nos três canais](https://api-wa.me/blog/wame-api-primeiro-envio-whatsapp-instagram-messenger) 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](https://portal.api-wa.me/sign-up) ## 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. ## Continue lendo [### Como criar um chatbot de IA com a API da OpenAI para responder no WhatsApp Um webhook, uma chamada à API da OpenAI e uma resposta pela WAME API: o código completo de um chatbot de IA que atende no WhatsApp, Instagram e Messenger. Com memória por contato, controle de custo e o que fazer quando a IA não deve responder.](https://api-wa.me/blog/chatbot-ia-openai-whatsapp)[### Cobrança por Pix dentro do WhatsApp pela API: como enviar e o que muda na conversão Mandar o código Pix no WhatsApp resolve o pior ponto da cobrança digital: o cliente não precisa sair do app. Como enviar a cobrança pela API, tratar a confirmação e evitar os erros que transformam a facilidade em suporte.](https://api-wa.me/blog/cobrar-pix-whatsapp-api)[### Erros da API do WhatsApp: o que cada um significa e como tratar A mensagem não saiu e o log diz apenas 'erro ao enviar'. Os erros que você vai encontrar de verdade — janela fechada, número inválido, template não aprovado, limite atingido, instância caída — e o tratamento certo para cada um.](https://api-wa.me/blog/erros-api-whatsapp-como-tratar) [Voltar ao blog](https://api-wa.me/blog) ## Structured data ```json { "@context": "https://schema.org", "@type": "WebSite", "name": "WAME API", "alternateName": "API Oficial e Não Oficial de WhatsApp, Instagram e Messenger", "url": "https://api-wa.me", "inLanguage": "pt-BR", "publisher": { "@id": "https://api-wa.me/#organization", "@type": "Organization", "name": "WAME API", "url": "https://api-wa.me" } } { "@context": "https://schema.org", "@type": "Organization", "@id": "https://api-wa.me/#organization", "name": "WAME API", "alternateName": [ "WAME", "Wame API", "wame.api.br", "api-wa.me" ], "url": "https://api-wa.me", "logo": { "@type": "ImageObject", "url": "https://api-wa.me/images/web-app-manifest-512x512.png", "width": 512, "height": 512 }, "disambiguatingDescription": "WAME API é uma empresa brasileira de software, fundada em 2017 e parceira oficial da Meta (Meta Business Partner), que fornece APIs de WhatsApp, Instagram Direct e Messenger. Não tem relação com o wa.me, que é o encurtador de links operado pela WhatsApp LLC.", "identifier": { "@type": "PropertyValue", "propertyID": "INPI-BR", "name": "Pedido de registro de marca (INPI, classe NCL 42)", "value": "944724159" }, "foundingDate": "2017", "slogan": "Parceira Oficial da Meta — WhatsApp, Instagram e Messenger numa instância só. Desde 2017.", "description": "Plataforma brasileira e Parceira Oficial da Meta (Meta Business Partner) para as APIs oficiais de WhatsApp (Cloud API), Instagram Direct e Messenger — os três numa única instância, com os mesmos endpoints e um único formato de webhook. Também oferece a API não oficial via QR Code, na mesma plataforma. No mercado desde 2017, com mais de 50 mil instâncias criadas, 99,9% de uptime e suporte humano 24/7 em português. SDKs oficiais para Node.js/TypeScript e PHP.", "knowsAbout": [ "WhatsApp Cloud API oficial (Meta)", "API oficial de Instagram (Direct)", "API oficial de Messenger", "API multicanal Meta", "Meta Business Partner", "WhatsApp API", "API não oficial de WhatsApp", "automação de WhatsApp", "números virtuais", "webhooks" ], "sameAs": [ "https://github.com/wame-api", "https://www.linkedin.com/company/wameapi", "https://www.instagram.com/wame.api/", "https://www.youtube.com/@wameapi" ], "contactPoint": { "@type": "ContactPoint", "contactType": "customer support", "url": "https://api-wa.me/contact", "availableLanguage": [ "Portuguese" ] } } { "@context": "https://schema.org", "@type": "BlogPosting", "headline": "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. 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.", "image": "https://api-wa.me/blog/webhook-whatsapp-nao-chega-como-testar/opengraph-image", "datePublished": "2026-09-10", "dateModified": "2026-09-10", "author": { "@type": "Person", "name": "Raphael Serafim", "url": "https://github.com/raphaelvserafim", "sameAs": [ "https://github.com/raphaelvserafim" ] }, "publisher": { "@type": "Organization", "name": "api-wa.me", "logo": { "@type": "ImageObject", "url": "https://api-wa.me/images/screenshot.png" } }, "mainEntityOfPage": { "@type": "WebPage", "@id": "https://api-wa.me/blog/webhook-whatsapp-nao-chega-como-testar" }, "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", "inLanguage": "pt-BR" } { "@context": "https://schema.org", "@type": "BreadcrumbList", "itemListElement": [ { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://api-wa.me" }, { "@type": "ListItem", "position": 2, "name": "Blog da API do WhatsApp", "item": "https://api-wa.me/blog" }, { "@type": "ListItem", "position": 3, "name": "Webhook do WhatsApp não chega: as 7 causas e como testar em 30 segundos", "item": "https://api-wa.me/blog/webhook-whatsapp-nao-chega-como-testar" } ] } { "@context": "https://schema.org", "@type": "FAQPage", "mainEntity": [ { "@type": "Question", "name": "Como testar se o webhook do WhatsApp está sendo enviado?", "acceptedAnswer": { "@type": "Answer", "text": "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." } }, { "@type": "Question", "name": "Por que meu webhook recebe status de entrega mas não mensagens?", "acceptedAnswer": { "@type": "Answer", "text": "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." } }, { "@type": "Question", "name": "O webhook chega duplicado. Por quê?", "acceptedAnswer": { "@type": "Answer", "text": "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." } }, { "@type": "Question", "name": "O webhook funciona em localhost?", "acceptedAnswer": { "@type": "Answer", "text": "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." } }, { "@type": "Question", "name": "Preciso de HTTPS no webhook?", "acceptedAnswer": { "@type": "Answer", "text": "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." } } ] } ```