1

Webhook do WhatsApp Cloud API | como validar o X-Hub-Signature-256 em Node.js e PHP e os 3 erros que quebram a assinatura

Quem integra o WhatsApp Cloud API costuma fazer o webhook funcionar em meia hora e nunca mais olhar para ele. Só que essa URL é pública: qualquer pessoa que descobrir o endereço pode mandar um POST com um JSON no formato da Meta e fazer o seu sistema "receber" uma mensagem que nunca existiu. Se o webhook dispara ações (abrir ticket, emitir segunda via de boleto, responder com IA), isso vira problema real.

A Meta resolve isso assinando cada entrega. Neste post mostro como validar essa assinatura em Node.js e em PHP, com código que testei, e os três erros que fazem a assinatura "nunca bater".

Contexto: sou o Rodrigo, Software Engineer do OmniPlug, infraestrutura de mensageria para WhatsApp e Instagram que CRMs, helpdesks e ERPs usam por baixo. Validar webhook da Meta faz parte do nosso dia a dia.

Como a Meta assina o webhook

Cada POST que chega no seu webhook traz o header:

X-Hub-Signature-256: sha256=<hash em hexadecimal>

O hash é um HMAC-SHA256 do corpo da requisição, usando como chave o App Secret do seu app (Painel do app → Configurações do app → Básico). Para validar:

  1. Leia o corpo cru da requisição, byte a byte, antes de qualquer parse.
  2. Calcule HMAC-SHA256(corpo_cru, APP_SECRET) em hexadecimal.
  3. Compare com o que vem depois de sha256= usando comparação em tempo constante.
  4. Bateu: processe. Não bateu: responda 401 e descarte.

O App Secret não é o token de acesso nem o verify token. O verify token só serve para o handshake inicial (o GET com hub.challenge), que também está nos exemplos.

Node.js (Express)

// server.js
const crypto = require('node:crypto');
const express = require('express');

const APP_SECRET = process.env.META_APP_SECRET;
const VERIFY_TOKEN = process.env.META_VERIFY_TOKEN;

const app = express();

// Handshake de verificação (GET), feito uma vez ao cadastrar a URL
app.get('/webhooks/whatsapp', (req, res) => {
  const mode = req.query['hub.mode'];
  const token = req.query['hub.verify_token'];
  const challenge = req.query['hub.challenge'];
  if (mode === 'subscribe' && token === VERIFY_TOKEN) {
    return res.status(200).send(challenge);
  }
  return res.sendStatus(403);
});

function assinaturaValida(rawBody, header, secret) {
  if (typeof header !== 'string' || !header.startsWith('sha256=')) return false;
  const recebida = Buffer.from(header.slice('sha256='.length), 'hex');
  const esperada = crypto.createHmac('sha256', secret).update(rawBody).digest();
  // timingSafeEqual lança erro se os tamanhos forem diferentes
  return recebida.length === esperada.length && crypto.timingSafeEqual(recebida, esperada);
}

// Eventos (POST): o corpo chega como Buffer, sem passar pelo parser de JSON
app.post(
  '/webhooks/whatsapp',
  express.raw({ type: 'application/json', limit: '1mb' }),
  (req, res) => {
    if (!assinaturaValida(req.body, req.get('x-hub-signature-256'), APP_SECRET)) {
      return res.sendStatus(401);
    }
    const payload = JSON.parse(req.body.toString('utf8')); // só agora
    res.sendStatus(200); // responda rápido, processe depois
    setImmediate(() => processar(payload));
  }
);

function processar(payload) {
  for (const entry of payload.entry ?? []) {
    for (const change of entry.changes ?? []) {
      for (const msg of change.value?.messages ?? []) {
        console.log('mensagem', msg.id, 'de', msg.from, msg.text?.body);
      }
    }
  }
}

app.listen(process.env.PORT || 3000);

O ponto central é o express.raw() só nessa rota. Se o seu app tem app.use(express.json()) global registrado antes, o corpo já chega como objeto e você perdeu os bytes originais. Nesse caso, ou registre a rota do webhook antes do middleware global, ou use a opção verify do express.json() para guardar o Buffer em req.rawBody.

PHP (puro, funciona em qualquer framework)

<?php
// webhook.php
$appSecret   = getenv('META_APP_SECRET');
$verifyToken = getenv('META_VERIFY_TOKEN');

// Handshake de verificação (GET)
if ($_SERVER['REQUEST_METHOD'] === 'GET') {
    // O PHP troca "." por "_" nos nomes da query string: hub.mode vira hub_mode
    $mode      = $_GET['hub_mode'] ?? '';
    $token     = $_GET['hub_verify_token'] ?? '';
    $challenge = $_GET['hub_challenge'] ?? '';

    if ($mode === 'subscribe' && is_string($verifyToken) && hash_equals($verifyToken, $token)) {
        header('Content-Type: text/plain');
        echo $challenge;
    } else {
        http_response_code(403);
    }
    exit;
}

// Eventos (POST): leia o corpo cru, nunca re-serialize
$rawBody = file_get_contents('php://input');
$header  = $_SERVER['HTTP_X_HUB_SIGNATURE_256'] ?? '';

function assinaturaValida(string $rawBody, string $header, string $secret): bool
{
    if (strncmp($header, 'sha256=', 7) !== 0) {
        return false;
    }
    $esperada = hash_hmac('sha256', $rawBody, $secret);
    return hash_equals($esperada, strtolower(substr($header, 7)));
}

if (!is_string($appSecret) || !assinaturaValida($rawBody, $header, $appSecret)) {
    http_response_code(401);
    exit;
}

$payload = json_decode($rawBody, true);
http_response_code(200);

// Em produção, coloque $payload numa fila e retorne. Aqui só registramos.
foreach ($payload['entry'] ?? [] as $entry) {
    foreach ($entry['changes'] ?? [] as $change) {
        foreach ($change['value']['messages'] ?? [] as $msg) {
            error_log("mensagem {$msg['id']} de {$msg['from']}");
        }
    }
}

No Laravel, o equivalente de php://input é $request->getContent(), e o header sai de $request->header('X-Hub-Signature-256'). Não use $request->all() nem json_encode($request->json()->all()) para calcular o hash.

O detalhe do hub_mode pega muita gente: o PHP converte pontos em underscores nos nomes de parâmetros, então $_GET['hub.mode'] nunca existe.

Testando sem a Meta

Você consegue gerar uma assinatura válida com openssl e disparar contra o seu servidor local:

export META_APP_SECRET=segredo_teste
SIG=$(openssl dgst -sha256 -hmac "$META_APP_SECRET" -r body.json | cut -d' ' -f1)

# deve retornar 200
curl -i -H 'Content-Type: application/json' \
  -H "X-Hub-Signature-256: sha256=$SIG" \
  --data-binary @body.json http://localhost:3000/webhooks/whatsapp

# altere um byte do arquivo e rode de novo: deve retornar 401

Use --data-binary, não -d: o -d remove quebras de linha e muda o corpo. Nos meus testes, os dois servidores responderam 200 para o corpo assinado e 401 para corpo alterado, header ausente e header malformado.

Os 3 erros que fazem a assinatura nunca bater

1. Calcular o hash sobre o JSON re-serializado. É o erro mais comum. A Meta pode mandar caracteres especiais escapados ("Jo\u00e3o" em vez de "João"). Quando você faz JSON.stringify(JSON.parse(corpo)), o Node devolve João em UTF-8, os bytes mudam e o hash muda. Testei com um payload contendo "João" e "2ª via" escapados: o hash do corpo cru batia, o do corpo re-serializado não. No PHP, json_encode escapa Unicode por padrão e às vezes coincide, por sorte; basta o payload ter uma / (que vira \/) ou você usar JSON_UNESCAPED_UNICODE para quebrar. Regra: hash sempre no corpo cru.

2. Usar o segredo errado. A chave é o App Secret do app que recebe o webhook. Se você tem apps diferentes para homologação e produção, cada um tem o seu. Não é o token de acesso, nem o verify token.

3. Comparar com === ou ==. Funciona, mas vaza tempo de comparação e abre espaço para ataque de timing. Use crypto.timingSafeEqual no Node e hash_equals no PHP. No Node, verifique o tamanho antes, porque timingSafeEqual lança exceção com Buffers de tamanhos diferentes.

O que a assinatura não resolve: reentregas e replay

A assinatura prova que o corpo veio da Meta e não foi alterado. Ela não diz quando foi enviado. Dois efeitos práticos:

  • A Meta reentrega. Se o seu servidor não responder 200, a documentação diz que ela tenta de novo imediatamente e mais algumas vezes, com frequência decrescente, por até 7 dias. E pede que você trate duplicidade.
  • Uma requisição válida capturada pode ser reenviada por quem a interceptou, e a assinatura continua válida.

A defesa para os dois é a mesma: deduplicar pelo ID do evento. Para mensagens, use messages[].id (o wamid); para status, a combinação statuses[].id + statuses[].status. Grave numa tabela com índice único e ignore o que já foi visto. E responda 200 rápido, jogando o processamento numa fila, para não provocar reentregas por timeout.

Alguns provedores colocam um timestamp dentro da assinatura justamente para fechar a janela de replay. É o que fazemos no OmniPlug: a validação do X-Hub-Signature-256 e a deduplicação das reentregas da Meta já acontecem na entrada. O seu sistema recebe um webhook nosso, assinado com t=<unix>,v1=<hex> (HMAC sobre <t>.<corpo>, tolerância de 5 minutos) e com um X-Omniplug-Event-Id fixo entre tentativas. O formato completo está na documentação de recebimento de webhooks. O Stripe usa um esquema parecido; se você está desenhando o webhook do seu próprio SaaS, vale copiar a ideia.

Se quiser ir além, a Meta também suporta mTLS nos webhooks, configurado por app. Para a maioria dos casos, assinatura + deduplicação já resolve.

Dúvidas ou outro framework que você queira ver (Laravel, NestJS, Go)? Comenta aí.

Carregando publicação patrocinada...
1

Ótimo passo a passo, principalmente o detalhe do express.raw() antes do parser global. Duas coisas que costumam aparecer depois que o webhook já está em produção:

  1. A assinatura não tem timestamp. Um POST válido capturado continua válido para sempre, e a própria Meta reenvia a entrega quando não recebe o 200 a tempo. O HMAC garante a origem, mas não garante "uma vez só". Antes de disparar a ação, deduplique pelo messages[].id (o wamid) e pelos ids de statuses: uma chave única no banco já resolve.

  2. 200 + setImmediate perde evento em deploy ou crash. Se o processo reinicia entre a resposta e o processamento, a Meta considera entregue e você nunca viu a mensagem. Gravar o corpo cru numa tabela ou fila antes do 200 e processar de lá resolve, e ainda deixa um histórico para reprocessar quando algo der errado.

Vocês fazem essa deduplicação no OmniPlug ou deixam para o sistema do cliente?