O webhook do WhatsApp é o endereço HTTPS que a Meta chama com um JSON quando um cliente escreve para o número da empresa, quando uma mensagem sua é enviada, entregue, lida ou falha, e quando um modelo de mensagem muda de status. Na API oficial (Cloud API), a configuração tem quatro partes: responder à verificação da Meta, assinar os campos que você usa, inscrever o app na conta do WhatsApp Business (WABA) e conferir a assinatura X-Hub-Signature-256 em cada POST antes de devolver HTTP 200.
O trabalho vem depois: a Meta reenvia por até sete dias, manda duplicados, não garante ordem e não tem API para evento perdido, então o receptor grava primeiro, descarta repetidos e processa depois. Este guia segue as referências da Meta lidas em 25 de setembro de 2026, na Graph API v26.0, versão atual naquela data. Token, número e primeiro disparo estão em como funciona a WhatsApp Cloud API.
Como configurar, passo a passo
- Publique um endpoint HTTPS que aceite GET e POST, com certificado TLS válido; a Meta recusa certificado autoassinado.
- Responda à verificação. Ao salvar a URL de callback e o token de verificação no painel do app (Use cases > Customize > Configuration; WhatsApp > Configuration em apps anteriores a dezembro de 2025), a Meta manda um GET com
hub.mode=subscribe,hub.challengeehub.verify_token. Se o token bater com o seu, devolva 200 com o challenge no corpo; se não, um código 4xx. - Assine os campos.
messagestraz mensagens recebidas e status das enviadas. Para modelos, somemessage_template_status_updateetemplate_category_update;user_preferencesavisa quem parou de aceitar marketing. O token precisa dewhatsapp_business_messagingparamessagesewhatsapp_business_managementpara o resto. - Inscreva o app em cada WABA com
POST https://graph.facebook.com/v26.0/<WABA_ID>/subscribed_apps. A Meta exige uma inscrição por WABA. - Coloque o app em modo Live. Segundo a Meta, alguns webhooks não saem em modo de desenvolvimento.
Se o botão Test do painel chega ao servidor e as mensagens reais de clientes não, confira os passos 4 e 5 primeiro.
Receptor mínimo em Node.js
Código ilustrativo, não de produção. O endpoint de teste da Meta converte o JSON e não confere a assinatura; não copie essa parte. O HMAC cobre os bytes exatos que a Meta enviou, então leia o corpo cru antes de converter.
import crypto from "node:crypto";
import express from "express";
const app = express();
const { VERIFY_TOKEN, APP_SECRET } = process.env;
app.get("/webhooks/whatsapp", (req, res) => {
const ok = req.query["hub.mode"] === "subscribe" &&
req.query["hub.verify_token"] === VERIFY_TOKEN;
if (ok) res.status(200).send(req.query["hub.challenge"]);
else res.sendStatus(403);
});
app.post("/webhooks/whatsapp", express.raw({ type: "application/json" }), async (req, res) => {
const recebida = Buffer.from(req.get("X-Hub-Signature-256") ?? "");
const esperada = Buffer.from("sha256=" +
crypto.createHmac("sha256", APP_SECRET).update(req.body).digest("hex"));
if (recebida.length !== esperada.length || !crypto.timingSafeEqual(recebida, esperada)) {
return res.sendStatus(401);
}
await gravarBruto(req.body); // primeiro grava em tabela ou fila
res.sendStatus(200); // depois confirma
});
// Worker: aplica cada payload gravado uma única vez
function aplicar(payload) {
for (const entry of payload.entry ?? []) {
for (const { field, value } of entry.changes ?? []) {
if (field === "messages") {
for (const m of value.messages ?? []) inserirUmaVez(`in:${m.id}`, m);
for (const s of value.statuses ?? []) inserirUmaVez(`st:${s.id}:${s.status}`, s);
} else if (field === "message_template_status_update") {
inserirUmaVez(`tpl:${value.message_template_id}:${value.event}:${entry.time}`, value);
}
}
}
}
gravarBruto e inserirUmaVez representam o seu armazenamento: uma tabela com chave única, em que a mesma chave inserida de novo é ignorada (INSERT … ON CONFLICT DO NOTHING no PostgreSQL).
O JSON de uma mensagem recebida
Todo payload tem o mesmo envelope: object vale whatsapp_business_account, entry[].id é o ID da WABA e changes[].field diz qual campo chegou. Nos webhooks messages, value.metadata.phone_number_id indica qual dos seus números recebeu o evento. Uma mensagem de texto de cliente, só o value:
{
"contacts": [{ "profile": { "name": "Ana Souza" }, "wa_id": "5511987654321", "user_id": "BR.13491208655302741918" }],
"messages": [{
"from": "5511987654321",
"from_user_id": "BR.13491208655302741918",
"id": "wamid.HBgNNTUxMTk4NzY1NDMyMRUCABIYFjNB",
"timestamp": "1761656400",
"type": "text",
"text": { "body": "Meu pedido 4821 já saiu?" }
}]
}
O type varia (text, image, interactive, button, order, location, reaction e outros), e o objeto referral marca conversas vindas de anúncio de clique para o WhatsApp.
CRM que usa o telefone como chave precisa mudar em 2026. Desde o começo de abril, todo webhook messages traz user_id, o ID de usuário por empresa, que começa pelo código do país (BR. para clientes brasileiros) e vale só no seu portfólio empresarial. Se o cliente adotar nome de usuário (recurso que o WhatsApp libera aos poucos em 2026), from e wa_id somem do payload, salvo se aquele número da empresa trocou mensagens ou ligações com o telefone dele nos últimos 30 dias ou se o número está na agenda de contatos da Meta. Use user_id como chave, guarde o telefone como atributo e assine user_id_update, que avisa quando esse ID muda.
Status de entrega e eventos de modelos
Cada mensagem enviada pode gerar três webhooks de status: enviada, entregue e lida.
status | O que significa na referência da Meta |
|---|---|
sent | Saiu dos servidores da Meta (um tique) |
delivered | Chegou ao celular do cliente (dois tiques) |
read | Foi exibida na conversa aberta (dois tiques azuis) |
failed | Não foi enviada ou entregue; traz errors |
A Meta pula o delivered quando a mensagem é lida ao chegar, e nenhuma página de webhook dela garante ordem: guarde o status mais avançado, não o último recebido. Para ligar o status ao pedido, envie biz_opaque_callback_data com a mensagem; o valor volta nos webhooks de status.
Um failed traz errors[].code, title e error_data.details. Os códigos mais comuns no atendimento:
| Código | Descrição da Meta | O que fazer |
|---|---|---|
| 131047 | Mais de 24 horas desde a última resposta do cliente | Enviar um modelo de mensagem |
| 131026 | Mensagem não entregue (sem WhatsApp, app antigo, termos não aceitos) | Falar com o cliente por outro canal |
| 131049 | Não entregue para manter o engajamento saudável | Esperar ao menos 24 horas antes de reenviar |
| 131050 | O cliente parou de receber seu marketing | Não reenviar; acompanhar user_preferences |
| 131042 | Problema na forma de pagamento da conta | Corrigir o faturamento no Meta Business Suite |
O objeto pricing ajuda a conferir a fatura. Desde 1º de outubro de 2026, cada resposta de atendimento para o Brasil custa R$ 0,0350 depois de uma franquia de 1.000 mensagens grátis por número por mês, e o modelo de utilidade enviado dentro da janela de 24 horas custa R$ 0,0350. No webhook de status, a resposta dentro da franquia chega com pricing.type free_customer_service e a cobrada com regular, e a categoria vem em pricing.category. O objeto aparece no sent e de novo no delivered ou no read: conte cada ID de mensagem uma vez. Faixas de volume não vêm no webhook (use pricing_analytics). Desde a v24.0, conversation só aparece em janela gratuita de ponto de entrada, e billable será descontinuado.
Eventos de modelos. O message_template_status_update manda um event (APPROVED, REJECTED, PAUSED, DISABLED e outros) com ID, nome, idioma, categoria e reason; na reprovação por INVALID_FORMAT, vem também a correção sugerida pela Meta. Ao receber PAUSED ou DISABLED, pare o disparo; o guia de templates do WhatsApp explica cada status.
Reenvios, duplicados e segurança
- Reenvio. Resposta diferente de 200 é reenviada na hora e depois com intervalos maiores, por até sete dias, e então descartada. Nenhuma API devolve webhooks antigos.
- Duplicados. O reenvio vai para todos os apps inscritos na WABA. Descarte repetidos pelo ID da mensagem mais o status.
- Lotes. Um POST pode trazer até 1.000 atualizações (sem garantia) e até 3 MB. Percorra todos os itens.
- Tempo de resposta. A Meta não publica prazo; a 360dialog, que repassa o formato da Meta, exige 200 em até 5 segundos. Confirme primeiro e processe numa fila.
- Quem está chamando. A assinatura vem primeiro. A Meta também oferece mTLS: o certificado de cliente (
client.webhooks.fbclientcerts.com) é assinado pela CA da própria Meta, que substituiu o DigiCert expirado em 15 de abril de 2026. A Meta prefere mTLS a lista de IPs, porque os endereços mudam.
Uma URL diferente por número
Por padrão, tudo vai para a URL de callback do app. Para desviar uma WABA ou um número, use POST /<WABA_ID>/subscribed_apps com override_callback_uri e verify_token, ou POST /<PHONE_NUMBER_ID> com o objeto webhook_configuration. A ordem é número, WABA, app, o que serve para número de homologação ou agência com vários clientes. Webhooks de modelos e de conta vão sempre para a URL do app.
Webhook do provedor ou da Meta?
Com BSP ou plataforma, seu servidor normalmente conversa com o provedor, que recebe os webhooks da Meta e repassa no formato dela ou no próprio, com assinatura e regras de reenvio próprias:
- A 360dialog repassa o payload da Cloud API sem mudar o formato, com webhook por número ou por WABA e autenticação Basic opcional na sua URL.
- A Twilio manda callbacks de status por remetente, Messaging Service ou mensagem, form-encoded por padrão e assinados com
X-Twilio-Signature; a Twilio orienta validar com o SDK dela.
O que cada ficha do catálogo registra sobre eventos de status no plano avaliado:
| O que o webhook do provedor informa | Plataformas |
|---|---|
| Entregue, lida e falha com motivo | 360dialog, Blip Platform (Plus em diante), Botmaker (adicional pago), Gupshup, Infobip, Sinch, Treble, Twilio, Zenvia, WATI (Pro e Business, não no Growth) |
| Status sem código de falha documentado | Poli Digital, VTEX CX Platform (Weni) |
| Só falhas | SendPulse (Pro): código e mensagem de erro; entregue e lida pela API de mensagens do chat |
| Sem evento de status | Status pela API: Kommo (Pro, Enterprise), Octadesk, respond.io, Umbler Talk (Impulso, Escala). Nada documentado: Huggy, BotConversa |
| Não encontrado em páginas públicas | Blip Go, Digisac, Manychat, RD Station Conversas |
Para o CRM ou o ERP receber entregue e lida sem consultar a API, fique com a primeira linha e confirme se o plano inclui webhooks. Como levar os eventos a um CRM está no guia de integração do WhatsApp com o HubSpot.
Quanto custa receber webhooks
A Meta não cobra pelo webhook; você paga a hospedagem e as mensagens que ele relata. Integrar direto é o caminho mais barato para receber todos os eventos, pago em horas de desenvolvimento. Entre os provedores, Gupshup e Twilio não cobram mensalidade, só por mensagem. Plataformas com webhook de status confirmado no plano avaliado, da mais barata à mais cara:
| Plataforma | Plano | Preço | Implantação | Nota |
|---|---|---|---|---|
| Twilio | Pay-as-you-go (Programmable Messaging + Studio) | Sem mensalidade, paga por mensagem | Sem taxa de implantação | 44,4 |
| SendPulse | Profissional (Pro), 500 subscribers | a partir de R$ 95/mês | Sem taxa de implantação | 81,4 |
| 360dialog | WhatsApp API Regular | a partir de € 49/mês | Sem taxa de implantação | 41,2 |
| Poli Digital | Plano Entrada | a partir de R$ 369,90/mês | + a partir de R$ 1.197,90 de implantação (única) | 52,5 |
| Gupshup | Console (Automate & Grow) | a partir de US$ 100/mês | Sem taxa de implantação | 44,9 |
| Botmaker | Standard | a partir de R$ 600/mês | Taxa de implantação incerta: fontes divergem | 64,6 |
| Zenvia | Specialist | a partir de R$ 700/mês | + R$ 649 de implantação (única) | 62,8 |
| VTEX CX Platform (Weni) | A partir de 1.000 conversas/mês | a partir de R$ 1.900/mês | Sem taxa de implantação | 63,7 |
| Treble | Base plan (SMB) | a partir de US$ 399/mês | Taxa de implantação não informada | 42,9 |
| Infobip | AgentOS | a partir de US$ 530/mês | + taxa de implantação sob consulta | 57,3 |
| Blip Platform | Super | a partir de R$ 7.292/mês | Taxa de implantação não informada | 64,4 |
| Sinch | Conversation API — WhatsApp channel | Enterprise: preço sob consulta | Taxa de implantação não informada | 46,8 |
As mensagens são cobradas à parte, pela tarifa da Meta, com acréscimo ou em pacote, conforme o provedor; o guia de preço da API do WhatsApp no Brasil soma tudo para um mês típico.
Guias relacionados
- Como funciona a WhatsApp Cloud API
- Templates do WhatsApp: como aprovar
- Disparo em massa pela API oficial do WhatsApp
- Cobrar pelo WhatsApp com Pix e link
- BSP do WhatsApp: o que é e como escolher
Sobre este guia
Escrito pela equipe editorial do WABA Index, catálogo independente de plataformas de WhatsApp Business para empresas que vendem para clientes no Brasil. Nenhuma plataforma paga por posição ou menção, e o site não usa links de afiliados.
Metodologia
Em 25 de setembro de 2026 lemos a documentação da Meta sobre webhooks, preços e IDs de usuário por empresa e as páginas de provedores das fontes. Recursos dos provedores vêm das fichas do catálogo; preços, tarifas e notas, dos dados do catálogo. Nada foi testado na prática; o código é ilustrativo, para a Graph API v26.0. A pontuação está explicada na metodologia.
Atualizado em
28 de outubro de 2026. Fatos e fontes foram conferidos em 25 de setembro de 2026; preços, tarifas da Meta e notas das tabelas são lidos dos dados do catálogo quando a página carrega.
Perguntas frequentes
Por que o teste do painel chega e as mensagens reais não?
Inscreva o app na WABA (POST /<WABA_ID>/subscribed_apps), confira a assinatura do campo messages e ponha o app em modo Live.
Por quanto tempo a Meta reenvia um webhook que falhou?
Por até sete dias, com intervalos crescentes. Depois o evento se perde de vez.
O webhook do WhatsApp tem custo?
Não da Meta. Nos provedores depende do plano: a Botmaker vende webhooks como adicional, e o Growth da WATI e o Essencial da Umbler Talk não têm.
Dá para saber pelo webhook se a mensagem foi cobrada?
Dá: pricing.type vem regular na cobrada e free_customer_service na gratuita, com a categoria em pricing.category.