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:
- Leia o corpo cru da requisição, byte a byte, antes de qualquer parse.
- Calcule
HMAC-SHA256(corpo_cru, APP_SECRET)em hexadecimal. - Compare com o que vem depois de
sha256=usando comparação em tempo constante. - 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í.