{"id":43,"date":"2026-10-20T19:07:40","date_gmt":"2026-10-20T19:07:40","guid":{"rendered":"https:\/\/vectalk.com.br\/blog\/webhook-whatsapp-api\/"},"modified":"2026-10-20T19:07:40","modified_gmt":"2026-10-20T19:07:40","slug":"webhook-whatsapp-api","status":"publish","type":"post","link":"https:\/\/vectalk.com.br\/blog\/webhook-whatsapp-api\/","title":{"rendered":"Webhooks da API do WhatsApp: guia pr\u00e1tico com exemplos"},"content":{"rendered":"\n

Atualizado em 20\/10\/2026<\/em><\/p>\n\n\n\n

O webhook da API do WhatsApp \u00e9 uma URL HTTPS do seu sistema que recebe, via POST<\/code>, cada evento da conta: mensagens recebidas, mudan\u00e7as de status (sent<\/code>, delivered<\/code>, read<\/code>, failed<\/code>) e alertas da conta. Um endpoint bem feito valida a origem da requisi\u00e7\u00e3o, responde 200 em poucos segundos, coloca o evento numa fila e processa em segundo plano, ignorando duplicados pelo ID. Na integra\u00e7\u00e3o direta com a Meta h\u00e1 tamb\u00e9m um passo de verifica\u00e7\u00e3o por GET<\/code>; na Vectalk, a URL \u00e9 registrada por API e recebe o mesmo payload da Meta.<\/p>\n\n\n\n

Este guia mostra o formato dos eventos, as diferen\u00e7as entre integrar direto e pela Vectalk, e um servidor completo em Node.js e em Python.<\/p>\n\n\n\n

Como o fluxo de eventos funciona<\/h2>\n\n\n\n

Na integra\u00e7\u00e3o direta, a Meta chama o endpoint configurado no seu app. Com a Vectalk, a Meta chama a Vectalk, que repassa o evento para todas as URLs ativas registradas para aquela inst\u00e2ncia:<\/p>\n\n\n\n

Direto:   Meta  \u2500\u2500POST\u2500\u2500\u25b6  seu endpoint\nVectalk:  Meta  \u2500\u2500POST\u2500\u2500\u25b6  Vectalk  \u2500\u2500POST\u2500\u2500\u25b6  suas URLs (uma ou v\u00e1rias)<\/code><\/pre>\n\n\n\n
O corpo \u00e9 o mesmo nos dois casos. O que muda \u00e9 como a URL \u00e9 cadastrada e como a requisi\u00e7\u00e3o \u00e9 autenticada.<\/p>\n\n\n\n
Aspecto<\/th>Cloud API direta<\/th>Vectalk<\/th><\/tr><\/thead>
Cadastro da URL<\/td>Painel de Apps > WhatsApp > Configura\u00e7\u00e3o<\/td>POST \/api\/webhooks<\/code> com instance_id<\/code>, url<\/code> e name<\/code><\/td><\/tr>
Verifica\u00e7\u00e3o do endpoint<\/td>GET<\/code> com hub.mode<\/code>, hub.verify_token<\/code> e hub.challenge<\/code><\/td>N\u00e3o descrita na documenta\u00e7\u00e3o da Vectalk<\/td><\/tr>
Assinatura<\/td>Header X-Hub-Signature-256<\/code> (HMAC-SHA256 com o App Secret)<\/td>N\u00e3o descrita na documenta\u00e7\u00e3o da Vectalk<\/td><\/tr>
URLs por conta<\/td>Um endpoint por app (com substitui\u00e7\u00f5es por conta ou n\u00famero)<\/td>V\u00e1rias URLs por inst\u00e2ncia, todas recebem o mesmo evento<\/td><\/tr>
Tempo de resposta<\/td>A Meta reenvia se n\u00e3o receber 200<\/td>Responder 200 em menos de 20 segundos; sen\u00e3o a Vectalk reenvia<\/td><\/tr>
Novas tentativas<\/td>Frequ\u00eancia decrescente por at\u00e9 7 dias<\/td>Reenvio documentado, sem prazo informado<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
Fontes: webhooks da Cloud API<\/a> (atualizada em 26\/06\/2026), primeiros passos com webhooks da Graph API<\/a> e webhooks na documenta\u00e7\u00e3o da Vectalk<\/a>.<\/p>\n\n\n\n
Registrando o webhook na Vectalk<\/h2>\n\n\n\n
curl -X POST https:\/\/apis.vectalk.com.br\/api\/webhooks \\\n  -H \"Authorization: Bearer SEU_TOKEN\" \\\n  -H \"Content-Type: application\/json\" \\\n  -d '{\n    \"instance_id\": \"SEU_INSTANCE_ID\",\n    \"url\": \"https:\/\/meuapp.com.br\/whatsapp\/eventos\",\n    \"name\": \"Produ\u00e7\u00e3o\"\n  }'<\/code><\/pre>\n\n\n\n
A resposta traz o id<\/code> do webhook e active: true<\/code>. Com PATCH<\/code> no mesmo recurso voc\u00ea troca a URL, o nome ou desativa o webhook; os endpoints est\u00e3o em Registrar webhook<\/a> e Atualizar webhook<\/a>. A URL precisa ser HTTPS.<\/p>\n\n\n\n
Ter v\u00e1rias URLs por inst\u00e2ncia ajuda em dois casos: separar produ\u00e7\u00e3o e homologa\u00e7\u00e3o e mandar o mesmo evento para dois sistemas (o CRM e o data warehouse, por exemplo) sem montar um repasse pr\u00f3prio.<\/p>\n\n\n\n
Verifica\u00e7\u00e3o do endpoint (integra\u00e7\u00e3o direta)<\/h2>\n\n\n\n
Quando voc\u00ea configura o webhook no painel da Meta, ela faz um GET<\/code> na sua URL com tr\u00eas par\u00e2metros:<\/p>\n\n\n\n
GET https:\/\/meuapp.com.br\/whatsapp\/eventos?hub.mode=subscribe&hub.challenge=1158201444&hub.verify_token=meu-token-secreto<\/code><\/pre>\n\n\n\n
O endpoint deve conferir se hub.verify_token<\/code> \u00e9 igual ao valor que voc\u00ea definiu no painel e devolver o hub.challenge<\/code> no corpo, com status 200. Qualquer outra resposta faz a verifica\u00e7\u00e3o falhar.<\/p>\n\n\n\n
Os payloads que voc\u00ea vai receber<\/h2>\n\n\n\n
Todo evento chega com object: \"whatsapp_business_account\"<\/code> e uma lista entry<\/code>. Cada entry<\/code> tem uma lista changes<\/code>, e cada change<\/code> tem field<\/code> e value<\/code>. Para mensagens e status, field<\/code> \u00e9 messages<\/code>.<\/p>\n\n\n\n
Mensagem recebida<\/h3>\n\n\n\n
{\n  \"object\": \"whatsapp_business_account\",\n  \"entry\": [{\n    \"id\": \"WABA_ID\",\n    \"changes\": [{\n      \"field\": \"messages\",\n      \"value\": {\n        \"messaging_product\": \"whatsapp\",\n        \"metadata\": {\n          \"display_phone_number\": \"558430000000\",\n          \"phone_number_id\": \"PHONE_NUMBER_ID\"\n        },\n        \"contacts\": [{ \"profile\": { \"name\": \"Jo\u00e3o Silva\" }, \"wa_id\": \"5584988888888\" }],\n        \"messages\": [{\n          \"from\": \"5584988888888\",\n          \"id\": \"wamid.HBgLNTUx...\",\n          \"timestamp\": \"1760000000\",\n          \"type\": \"text\",\n          \"text\": { \"body\": \"Ol\u00e1, quero mais informa\u00e7\u00f5es\" }\n        }]\n      }\n    }]\n  }]\n}<\/code><\/pre>\n\n\n\n
O campo type<\/code> diz onde est\u00e1 o conte\u00fado. Os mais comuns:<\/p>\n\n\n\n
type<\/code><\/th>Onde ler<\/th><\/tr><\/thead>
text<\/code><\/td>text.body<\/code><\/td><\/tr>
image<\/code>, video<\/code>, audio<\/code>, document<\/code>, sticker<\/code><\/td><tipo>.id<\/code> (baixe pelo endpoint de m\u00eddia), caption<\/code>, filename<\/code><\/td><\/tr>
interactive<\/code><\/td>interactive.button_reply<\/code> ou interactive.list_reply<\/code><\/td><\/tr>
location<\/code><\/td>location.latitude<\/code>, location.longitude<\/code><\/td><\/tr>
reaction<\/code><\/td>reaction.message_id<\/code>, reaction.emoji<\/code><\/td><\/tr>
order<\/code><\/td>order.catalog_id<\/code>, order.product_items[]<\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
Status de mensagem enviada<\/h3>\n\n\n\n
{\n  \"object\": \"whatsapp_business_account\",\n  \"entry\": [{\n    \"id\": \"WABA_ID\",\n    \"changes\": [{\n      \"field\": \"messages\",\n      \"value\": {\n        \"messaging_product\": \"whatsapp\",\n        \"metadata\": { \"display_phone_number\": \"558430000000\", \"phone_number_id\": \"PHONE_NUMBER_ID\" },\n        \"statuses\": [{\n          \"id\": \"wamid.HBgLNTUx...\",\n          \"status\": \"delivered\",\n          \"timestamp\": \"1760000010\",\n          \"recipient_id\": \"5584988888888\",\n          \"pricing\": { \"billable\": true, \"pricing_model\": \"PMP\", \"type\": \"regular\", \"category\": \"utility\" }\n        }]\n      }\n    }]\n  }]\n}<\/code><\/pre>\n\n\n\n
O id<\/code> do status \u00e9 o wamid<\/code> devolvido quando voc\u00ea enviou a mensagem. Quando status<\/code> \u00e9 failed<\/code>, o objeto traz errors[]<\/code> com code<\/code>, title<\/code> e message<\/code>. O objeto pricing<\/code> indica categoria e se a mensagem \u00e9 cobr\u00e1vel; a refer\u00eancia completa est\u00e1 na documenta\u00e7\u00e3o do webhook de status<\/a>. Para entender o que cada categoria custa, veja Quanto custa a API do WhatsApp no Brasil em 2026<\/a>.<\/p>\n\n\n\n
Um mesmo POST<\/code> pode trazer v\u00e1rias mensagens ou v\u00e1rios status. Itere as listas em vez de ler s\u00f3 o primeiro item.<\/p>\n\n\n\n
Boas pr\u00e1ticas<\/h2>\n\n\n\n
Responda 200 r\u00e1pido e processe depois<\/h3>\n\n\n\n
O endpoint n\u00e3o deve chamar o seu banco, a IA ou outra API antes de responder. Grave o corpo bruto numa fila (Redis, SQS, RabbitMQ, uma tabela de eventos) e devolva 200. Um worker separado faz o trabalho pesado. A Vectalk documenta um limite de 20 segundos para a resposta; fique bem abaixo disso.<\/p>\n\n\n\n
Seja idempotente<\/h3>\n\n\n\n
A Meta avisa que as novas tentativas podem duplicar notifica\u00e7\u00f5es, e um proxy tamb\u00e9m pode reenviar. Use o id<\/code> da mensagem (ou a combina\u00e7\u00e3o id<\/code> + status<\/code>, no caso de status) como chave \u00fanica. Se a chave j\u00e1 foi processada, descarte.<\/p>\n\n\n\n
Valide a assinatura<\/h3>\n\n\n\n
Na integra\u00e7\u00e3o direta, a Meta assina cada POST<\/code> com HMAC-SHA256 do corpo, usando o App Secret do seu app, e envia o resultado no header X-Hub-Signature-256<\/code> no formato sha256=<hash><\/code>. Calcule o hash sobre o corpo bruto<\/strong>, antes de qualquer parse de JSON, e compare em tempo constante. Com a Vectalk, siga o mecanismo de autentica\u00e7\u00e3o que a Vectalk indicar para as requisi\u00e7\u00f5es repassadas; enquanto isso n\u00e3o estiver definido no seu ambiente, use uma URL com caminho dif\u00edcil de adivinhar, restrinja o endpoint a HTTPS e n\u00e3o confie no conte\u00fado para a\u00e7\u00f5es sens\u00edveis sem checar o phone_number_id<\/code> esperado.<\/p>\n\n\n\n
N\u00e3o dependa da ordem<\/h3>\n\n\n\n
delivered<\/code> pode chegar antes de sent<\/code>, e read<\/code> pode chegar sem delivered<\/code>. Guarde o status mais avan\u00e7ado e o timestamp<\/code> de cada um, sem regredir.<\/p>\n\n\n\n
Planeje para payloads grandes<\/h3>\n\n\n\n
A Meta informa que os payloads de webhook podem ter at\u00e9 3 MB. Ajuste o limite de corpo do seu servidor (o padr\u00e3o do Express \u00e9 100 kb).<\/p>\n\n\n\n
Monitore<\/h3>\n\n\n\n
Registre quantos eventos chegam por minuto e quantos falham no worker. Uma queda brusca de eventos de mensagens \u00e9, muitas vezes, o primeiro sinal de webhook desativado, certificado vencido ou n\u00famero desconectado.<\/p>\n\n\n\n
Exemplo completo em Node.js (Express)<\/h2>\n\n\n\n
import express from 'express'\nimport crypto from 'node:crypto'\nimport { createClient } from 'redis'\n\nconst app = express()\nconst redis = createClient({ url: process.env.REDIS_URL })\nawait redis.connect()\n\nconst VERIFY_TOKEN = process.env.WHATSAPP_VERIFY_TOKEN \/\/ integra\u00e7\u00e3o direta\nconst APP_SECRET = process.env.META_APP_SECRET        \/\/ integra\u00e7\u00e3o direta\n\n\/\/ Guarda o corpo bruto para validar a assinatura\napp.use('\/whatsapp\/eventos', express.raw({ type: 'application\/json', limit: '3mb' }))\n\n\/\/ Verifica\u00e7\u00e3o do endpoint (s\u00f3 na integra\u00e7\u00e3o direta com a Meta)\napp.get('\/whatsapp\/eventos', (req, res) => {\n  const { 'hub.mode': mode, 'hub.verify_token': token, 'hub.challenge': challenge } = req.query\n  if (mode === 'subscribe' && token === VERIFY_TOKEN) return res.status(200).send(challenge)\n  return res.sendStatus(403)\n})\n\nfunction assinaturaValida(req) {\n  const header = req.get('X-Hub-Signature-256') || ''\n  const esperado = 'sha256=' + crypto.createHmac('sha256', APP_SECRET).update(req.body).digest('hex')\n  const a = Buffer.from(header)\n  const b = Buffer.from(esperado)\n  return a.length === b.length && crypto.timingSafeEqual(a, b)\n}\n\napp.post('\/whatsapp\/eventos', async (req, res) => {\n  if (APP_SECRET && !assinaturaValida(req)) return res.sendStatus(401)\n  await redis.lPush('whatsapp:eventos', req.body.toString('utf8'))\n  res.sendStatus(200)\n})\n\napp.listen(3000)<\/code><\/pre>\n\n\n\n
E o worker, que consome a fila e descarta duplicados:<\/p>\n\n\n\n
async function processar(evento) {\n  for (const entry of evento.entry ?? []) {\n    for (const change of entry.changes ?? []) {\n      const v = change.value ?? {}\n      for (const msg of v.messages ?? []) {\n        const novo = await redis.set(`wa:msg:${msg.id}`, '1', { NX: true, EX: 60 * 60 * 24 * 8 })\n        if (!novo) continue \/\/ duplicado\n        await tratarMensagem(v.metadata.phone_number_id, msg) \/\/ sua regra de neg\u00f3cio\n      }\n      for (const st of v.statuses ?? []) {\n        const novo = await redis.set(`wa:st:${st.id}:${st.status}`, '1', { NX: true, EX: 60 * 60 * 24 * 8 })\n        if (!novo) continue\n        await atualizarStatus(st) \/\/ grava status, erros e pricing\n      }\n    }\n  }\n}\n\nwhile (true) {\n  const item = await redis.brPop('whatsapp:eventos', 0)\n  try {\n    await processar(JSON.parse(item.element))\n  } catch (err) {\n    console.error('falha ao processar evento', err)\n    await redis.lPush('whatsapp:eventos:erro', item.element)\n  }\n}<\/code><\/pre>\n\n\n\n
A expira\u00e7\u00e3o de oito dias nas chaves cobre a janela de novas tentativas da Meta, que vai at\u00e9 sete dias.<\/p>\n\n\n\n
Exemplo completo em Python (FastAPI)<\/h2>\n\n\n\n
import hashlib, hmac, json, os\nimport redis.asyncio as redis\nfrom fastapi import FastAPI, Request, Response\n\napp = FastAPI()\nr = redis.from_url(os.environ[\"REDIS_URL\"])\nVERIFY_TOKEN = os.environ.get(\"WHATSAPP_VERIFY_TOKEN\")  # integra\u00e7\u00e3o direta\nAPP_SECRET = os.environ.get(\"META_APP_SECRET\", \"\")      # integra\u00e7\u00e3o direta\n\n\n@app.get(\"\/whatsapp\/eventos\")\nasync def verificar(request: Request):\n    q = request.query_params\n    if q.get(\"hub.mode\") == \"subscribe\" and q.get(\"hub.verify_token\") == VERIFY_TOKEN:\n        return Response(content=q.get(\"hub.challenge\", \"\"), media_type=\"text\/plain\")\n    return Response(status_code=403)\n\n\ndef assinatura_valida(corpo: bytes, header: str) -> bool:\n    esperado = \"sha256=\" + hmac.new(APP_SECRET.encode(), corpo, hashlib.sha256).hexdigest()\n    return hmac.compare_digest(esperado, header or \"\")\n\n\n@app.post(\"\/whatsapp\/eventos\")\nasync def receber(request: Request):\n    corpo = await request.body()\n    if APP_SECRET and not assinatura_valida(corpo, request.headers.get(\"X-Hub-Signature-256\")):\n        return Response(status_code=401)\n    await r.lpush(\"whatsapp:eventos\", corpo)\n    return Response(status_code=200)<\/code><\/pre>\n\n\n\n
Worker em Python:<\/p>\n\n\n\n
import asyncio, json, os\nimport redis.asyncio as redis\n\nr = redis.from_url(os.environ[\"REDIS_URL\"])\nOITO_DIAS = 60 * 60 * 24 * 8\n\n\nasync def processar(evento: dict):\n    for entry in evento.get(\"entry\", []):\n        for change in entry.get(\"changes\", []):\n            v = change.get(\"value\", {})\n            for msg in v.get(\"messages\", []):\n                if not await r.set(f\"wa:msg:{msg['id']}\", 1, nx=True, ex=OITO_DIAS):\n                    continue\n                await tratar_mensagem(v[\"metadata\"][\"phone_number_id\"], msg)\n            for st in v.get(\"statuses\", []):\n                if not await r.set(f\"wa:st:{st['id']}:{st['status']}\", 1, nx=True, ex=OITO_DIAS):\n                    continue\n                await atualizar_status(st)\n\n\nasync def main():\n    while True:\n        _, item = await r.brpop(\"whatsapp:eventos\")\n        try:\n            await processar(json.loads(item))\n        except Exception as exc:\n            print(\"falha ao processar evento\", exc)\n            await r.lpush(\"whatsapp:eventos:erro\", item)\n\nasyncio.run(main())<\/code><\/pre>\n\n\n\n
As fun\u00e7\u00f5es tratar_mensagem<\/code> e atualizar_status<\/code> (e as equivalentes em Node) s\u00e3o a sua regra de neg\u00f3cio: responder, gravar no CRM, acionar um agente.<\/p>\n\n\n\n
O que fazer com cada tipo de evento no worker<\/h2>\n\n\n\n
Separar o tratamento por tipo de evento deixa o worker mais f\u00e1cil de manter. Uma divis\u00e3o que funciona bem:<\/p>\n\n\n\n