{"id":504,"date":"2026-10-28T16:04:32","date_gmt":"2026-10-28T16:04:32","guid":{"rendered":"https:\/\/vectalk.com.br\/blog\/assinatura-webhook-whatsapp\/"},"modified":"2026-10-28T16:04:43","modified_gmt":"2026-10-28T16:04:43","slug":"assinatura-webhook-whatsapp","status":"publish","type":"post","link":"https:\/\/vectalk.com.br\/blog\/assinatura-webhook-whatsapp\/","title":{"rendered":"Como validar a assinatura do webhook do WhatsApp (X-Hub-Signature-256)"},"content":{"rendered":"\n

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

Para validar a assinatura do webhook do WhatsApp, calcule um HMAC SHA-256 do corpo da requisi\u00e7\u00e3o usando o app secret<\/strong> do seu app da Meta como chave e compare o resultado com o valor do cabe\u00e7alho X-Hub-Signature-256<\/code>, que vem no formato sha256=<hash><\/code>. Se os dois forem iguais, o evento veio da Meta e n\u00e3o foi alterado no caminho. O detalhe que mais derruba a valida\u00e7\u00e3o \u00e9 calcular o hash sobre o JSON j\u00e1 interpretado pelo framework, e n\u00e3o sobre os bytes exatos que chegaram.<\/p>\n\n\n\n

Este guia mostra o passo a passo, c\u00f3digo pronto para Node.js (Express), Python (FastAPI e Flask) e PHP, e os erros mais comuns. Se voc\u00ea ainda est\u00e1 montando o endpoint, comece por webhook da API do WhatsApp<\/a> e volte aqui para a parte de seguran\u00e7a.<\/p>\n\n\n\n

Por que validar a assinatura<\/h2>\n\n\n\n

A URL do seu webhook \u00e9 p\u00fablica. Qualquer pessoa que descobrir o endere\u00e7o pode mandar um POST<\/code> com um JSON no formato da Meta, simulando uma mensagem de cliente, um pagamento confirmado por bot\u00e3o ou um status delivered<\/code> que nunca aconteceu. Sem valida\u00e7\u00e3o, seu sistema aceita tudo.<\/p>\n\n\n\n

A documenta\u00e7\u00e3o de webhooks da Graph API<\/a> diz que a Meta assina todas as notifica\u00e7\u00f5es com SHA-256 e envia a assinatura no cabe\u00e7alho X-Hub-Signature-256<\/code>, precedida de sha256=<\/code>. A valida\u00e7\u00e3o n\u00e3o \u00e9 obrigat\u00f3ria, mas a pr\u00f3pria Meta recomenda fazer. Na pr\u00e1tica, \u00e9 o que separa um webhook confi\u00e1vel de um endpoint aberto.<\/p>\n\n\n\n

As duas requisi\u00e7\u00f5es que o seu endpoint recebe<\/h2>\n\n\n\n

O mesmo endere\u00e7o recebe dois tipos de chamada, e cada uma tem sua checagem:<\/p>\n\n\n\n

Requisi\u00e7\u00e3o<\/th>Quando acontece<\/th>O que validar<\/th>Resposta<\/th><\/tr><\/thead>
GET<\/code> de verifica\u00e7\u00e3o<\/td>Ao configurar ou alterar a URL no painel do app<\/td>hub.mode<\/code> igual a subscribe<\/code> e hub.verify_token<\/code> igual ao token que voc\u00ea definiu<\/td>200<\/code> com o valor de hub.challenge<\/code><\/td><\/tr>
POST<\/code> de evento<\/td>Cada mensagem, status ou mudan\u00e7a na conta<\/td>X-Hub-Signature-256<\/code> contra o HMAC do corpo bruto<\/td>200<\/code> r\u00e1pido; processamento em fila<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

Segundo a p\u00e1gina Create a webhook endpoint<\/a>, se a verifica\u00e7\u00e3o for v\u00e1lida voc\u00ea responde 200<\/code> com o hub.challenge<\/code>; se n\u00e3o for, responde qualquer coisa diferente de 200<\/code> (um 403, por exemplo). A mesma p\u00e1gina exige certificado TLS v\u00e1lido no endpoint: certificados autoassinados n\u00e3o s\u00e3o aceitos.<\/p>\n\n\n\n

Note que o verify token<\/em> e o app secret<\/em> s\u00e3o coisas diferentes. O verify token \u00e9 uma string que voc\u00ea inventa e cadastra no painel; ele s\u00f3 serve para o GET<\/code>. O app secret \u00e9 gerado pela Meta e fica em Configura\u00e7\u00f5es do app > B\u00e1sico<\/strong>; \u00e9 ele que assina os POST<\/code>.<\/p>\n\n\n\n

Passo a passo da valida\u00e7\u00e3o<\/h2>\n\n\n\n
    \n
  1. Leia o corpo da requisi\u00e7\u00e3o como bytes<\/strong>, antes de qualquer parser de JSON.<\/li>\n\n\n
  2. Calcule HMAC-SHA256(chave = app secret, mensagem = corpo bruto)<\/code> e converta para hexadecimal.<\/li>\n\n\n
  3. Monte sha256=<\/code> + hash e compare com o cabe\u00e7alho X-Hub-Signature-256<\/code> usando compara\u00e7\u00e3o em tempo constante.<\/li>\n\n\n
  4. Se n\u00e3o bater, responda 401 ou 403 e descarte o evento.<\/li>\n\n\n
  5. Se bater, fa\u00e7a o parse do JSON, coloque o evento numa fila e responda 200<\/code>.<\/li>\n\n<\/ol>\n\n\n\n

    A compara\u00e7\u00e3o em tempo constante (crypto.timingSafeEqual<\/code>, hmac.compare_digest<\/code>, hash_equals<\/code>) evita que um atacante descubra o hash byte a byte medindo o tempo de resposta.<\/p>\n\n\n\n

    Exemplo em Node.js com Express<\/h2>\n\n\n\n

    O ponto central \u00e9 usar express.raw()<\/code> na rota do webhook, para que req.body<\/code> seja um Buffer<\/code> com os bytes originais:<\/p>\n\n\n\n

    import express from 'express';\nimport crypto from 'node:crypto';\n\nconst app = express();\nconst APP_SECRET = process.env.META_APP_SECRET;\nconst VERIFY_TOKEN = process.env.WEBHOOK_VERIFY_TOKEN;\n\n\/\/ GET de verifica\u00e7\u00e3o\napp.get('\/webhook', (req, res) => {\n  const mode = req.query['hub.mode'];\n  const token = req.query['hub.verify_token'];\n  const challenge = req.query['hub.challenge'];\n  if (mode === 'subscribe' && token === VERIFY_TOKEN) {\n    return res.status(200).send(challenge);\n  }\n  return res.sendStatus(403);\n});\n\n\/\/ POST de eventos: corpo bruto s\u00f3 nesta rota\napp.post('\/webhook', express.raw({ type: 'application\/json' }), (req, res) => {\n  const recebida = req.get('X-Hub-Signature-256') || '';\n  const esperada = 'sha256=' + crypto\n    .createHmac('sha256', APP_SECRET)\n    .update(req.body)\n    .digest('hex');\n\n  const a = Buffer.from(recebida);\n  const b = Buffer.from(esperada);\n  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {\n    return res.sendStatus(401);\n  }\n\n  const evento = JSON.parse(req.body.toString('utf8'));\n  res.sendStatus(200);\n  filaDeEventos.push(evento); \/\/ processe fora do ciclo da requisi\u00e7\u00e3o\n});\n\napp.use(express.json()); \/\/ demais rotas podem usar JSON normalmente\napp.listen(3000);<\/code><\/pre>\n\n\n\n
    Se a aplica\u00e7\u00e3o j\u00e1 tem app.use(express.json())<\/code> declarado antes dessa rota, o corpo chega interpretado e o hash n\u00e3o bate. Duas sa\u00eddas: declarar a rota do webhook antes do middleware global, ou guardar os bytes no pr\u00f3prio express.json<\/code>:<\/p>\n\n\n\n
    app.use(express.json({\n  verify: (req, _res, buf) => { req.rawBody = buf; },\n}));\n\/\/ depois, use req.rawBody no createHmac<\/code><\/pre>\n\n\n\n
    Exemplo em Python com FastAPI<\/h2>\n\n\n\n
    No FastAPI, await request.body()<\/code> devolve os bytes exatos. N\u00e3o use o modelo Pydantic do corpo para assinar:<\/p>\n\n\n\n
    import hashlib\nimport hmac\nimport json\nimport os\n\nfrom fastapi import FastAPI, HTTPException, Request, Response\n\napp = FastAPI()\nAPP_SECRET = os.environ[\"META_APP_SECRET\"].encode()\nVERIFY_TOKEN = os.environ[\"WEBHOOK_VERIFY_TOKEN\"]\n\n\n@app.get(\"\/webhook\")\nasync def verificar(request: Request):\n    p = request.query_params\n    if p.get(\"hub.mode\") == \"subscribe\" and p.get(\"hub.verify_token\") == VERIFY_TOKEN:\n        return Response(content=p.get(\"hub.challenge\", \"\"), media_type=\"text\/plain\")\n    raise HTTPException(status_code=403)\n\n\n@app.post(\"\/webhook\")\nasync def receber(request: Request):\n    corpo = await request.body()\n    recebida = request.headers.get(\"x-hub-signature-256\", \"\")\n    esperada = \"sha256=\" + hmac.new(APP_SECRET, corpo, hashlib.sha256).hexdigest()\n    if not hmac.compare_digest(recebida, esperada):\n        raise HTTPException(status_code=401)\n\n    evento = json.loads(corpo)\n    # enfileire o evento e responda r\u00e1pido\n    return {\"ok\": True}<\/code><\/pre>\n\n\n\n
    Exemplo em Python com Flask<\/h2>\n\n\n\n
    No Flask, use request.get_data()<\/code>, que devolve o corpo bruto:<\/p>\n\n\n\n
    import hashlib\nimport hmac\nimport os\n\nfrom flask import Flask, abort, request\n\napp = Flask(__name__)\nAPP_SECRET = os.environ[\"META_APP_SECRET\"].encode()\n\n\n@app.post(\"\/webhook\")\ndef receber():\n    corpo = request.get_data()\n    recebida = request.headers.get(\"X-Hub-Signature-256\", \"\")\n    esperada = \"sha256=\" + hmac.new(APP_SECRET, corpo, hashlib.sha256).hexdigest()\n    if not hmac.compare_digest(recebida, esperada):\n        abort(401)\n    evento = request.get_json()\n    return \"\", 200<\/code><\/pre>\n\n\n\n
    Exemplo em PHP<\/h2>\n\n\n\n
    Em PHP, o corpo bruto vem de php:\/\/input<\/code>. Aten\u00e7\u00e3o ao GET<\/code>: o PHP troca pontos por sublinhados nos nomes de par\u00e2metros, ent\u00e3o hub.verify_token<\/code> vira $_GET['hub_verify_token']<\/code>.<\/p>\n\n\n\n
    <?php\n$appSecret = getenv('META_APP_SECRET');\n$verifyToken = getenv('WEBHOOK_VERIFY_TOKEN');\n\nif ($_SERVER['REQUEST_METHOD'] === 'GET') {\n    if (($_GET['hub_mode'] ?? '') === 'subscribe'\n        && hash_equals($verifyToken, $_GET['hub_verify_token'] ?? '')) {\n        echo $_GET['hub_challenge'] ?? '';\n        exit;\n    }\n    http_response_code(403);\n    exit;\n}\n\n$corpo = file_get_contents('php:\/\/input');\n$recebida = $_SERVER['HTTP_X_HUB_SIGNATURE_256'] ?? '';\n$esperada = 'sha256=' . hash_hmac('sha256', $corpo, $appSecret);\n\nif (!hash_equals($esperada, $recebida)) {\n    http_response_code(401);\n    exit;\n}\n\n$evento = json_decode($corpo, true);\nhttp_response_code(200);<\/code><\/pre>\n\n\n\n
    Erros comuns que fazem a assinatura n\u00e3o bater<\/h2>\n\n\n\n
    Hash calculado sobre o JSON interpretado.<\/strong> \u00c9 o erro n\u00famero um. Ao fazer JSON.stringify(req.body)<\/code> ou json.dumps(payload)<\/code>, voc\u00ea gera um texto diferente do original: espa\u00e7os, ordem de chaves e escape de caracteres mudam. Um \u00fanico byte diferente muda o hash inteiro. Assine sempre os bytes que chegaram.<\/p>\n\n\n\n
    Encoding trocado.<\/strong> Converter o corpo para string com um charset errado (latin-1 em vez de UTF-8, por exemplo) altera nomes com acento e emojis. Trabalhe com bytes at\u00e9 a valida\u00e7\u00e3o terminar.<\/p>\n\n\n\n
    Secret errado.<\/strong> O valor certo \u00e9 o app secret do app que est\u00e1 inscrito no webhook. N\u00e3o \u00e9 o token de acesso, n\u00e3o \u00e9 o verify token e n\u00e3o \u00e9 o secret de outro app do mesmo portf\u00f3lio. Se voc\u00ea tem apps separados para teste e produ\u00e7\u00e3o, cada ambiente precisa do seu.<\/p>\n\n\n\n
    Prefixo ignorado.<\/strong> O cabe\u00e7alho traz sha256=<\/code> antes do hash. Ou voc\u00ea compara a string completa (como nos exemplos), ou remove o prefixo dos dois lados.<\/p>\n\n\n\n
    Middleware ou gateway alterando o corpo.<\/strong> Proxies, gateways de API e fun\u00e7\u00f5es serverless \u00e0s vezes reformatam ou codificam o corpo antes de entregar ao seu c\u00f3digo. Se a valida\u00e7\u00e3o falha s\u00f3 em produ\u00e7\u00e3o, registre o tamanho do corpo recebido e compare com o Content-Length<\/code>.<\/p>\n\n\n\n
    Secret trocado sem atualizar o servidor.<\/strong> Ao redefinir o app secret no painel, os eventos passam a chegar assinados com o novo valor. Se o servidor recusar tudo com 401, a Meta tenta reenviar: pela vis\u00e3o geral de webhooks<\/a>, as entregas que n\u00e3o recebem 200<\/code> s\u00e3o repetidas com frequ\u00eancia decrescente por at\u00e9 7 dias, e isso pode gerar eventos duplicados. Monitore a taxa de 401 do endpoint para pegar esse cen\u00e1rio cedo.<\/p>\n\n\n\n
    Boas pr\u00e1ticas depois da valida\u00e7\u00e3o<\/h2>\n\n\n\n