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

  1. Publique um endpoint HTTPS que aceite GET e POST, com certificado TLS válido; a Meta recusa certificado autoassinado.
  2. 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.challenge e hub.verify_token. Se o token bater com o seu, devolva 200 com o challenge no corpo; se não, um código 4xx.
  3. Assine os campos. messages traz mensagens recebidas e status das enviadas. Para modelos, some message_template_status_update e template_category_update; user_preferences avisa quem parou de aceitar marketing. O token precisa de whatsapp_business_messaging para messages e whatsapp_business_management para o resto.
  4. 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.
  5. 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.

statusO que significa na referência da Meta
sentSaiu dos servidores da Meta (um tique)
deliveredChegou ao celular do cliente (dois tiques)
readFoi exibida na conversa aberta (dois tiques azuis)
failedNã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ódigoDescrição da MetaO que fazer
131047Mais de 24 horas desde a última resposta do clienteEnviar um modelo de mensagem
131026Mensagem não entregue (sem WhatsApp, app antigo, termos não aceitos)Falar com o cliente por outro canal
131049Não entregue para manter o engajamento saudávelEsperar ao menos 24 horas antes de reenviar
131050O cliente parou de receber seu marketingNão reenviar; acompanhar user_preferences
131042Problema na forma de pagamento da contaCorrigir 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 informaPlataformas
Entregue, lida e falha com motivo360dialog, 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 documentadoPoli Digital, VTEX CX Platform (Weni)
Só falhasSendPulse (Pro): código e mensagem de erro; entregue e lida pela API de mensagens do chat
Sem evento de statusStatus pela API: Kommo (Pro, Enterprise), Octadesk, respond.io, Umbler Talk (Impulso, Escala). Nada documentado: Huggy, BotConversa
Não encontrado em páginas públicasBlip 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:

PlataformaPlanoPreçoImplantaçãoNota
TwilioPay-as-you-go (Programmable Messaging + Studio)Sem mensalidade, paga por mensagemSem taxa de implantação44,4
SendPulseProfissional (Pro), 500 subscribersa partir de R$ 95/mêsSem taxa de implantação81,4
360dialogWhatsApp API Regulara partir de € 49/mêsSem taxa de implantação41,2
Poli DigitalPlano Entradaa partir de R$ 369,90/mês+ a partir de R$ 1.197,90 de implantação (única)52,5
GupshupConsole (Automate & Grow)a partir de US$ 100/mêsSem taxa de implantação44,9
BotmakerStandarda partir de R$ 600/mêsTaxa de implantação incerta: fontes divergem64,6
ZenviaSpecialista 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êsa partir de R$ 1.900/mêsSem taxa de implantação63,7
TrebleBase plan (SMB)a partir de US$ 399/mêsTaxa de implantação não informada42,9
InfobipAgentOSa partir de US$ 530/mês+ taxa de implantação sob consulta57,3
Blip PlatformSupera partir de R$ 7.292/mêsTaxa de implantação não informada64,4
SinchConversation API — WhatsApp channelEnterprise: preço sob consultaTaxa de implantação não informada46,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

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.