Webhooks
Verificar a assinatura
Como confirmar que um webhook veio mesmo do Messajo, com exemplos em várias linguagens.
Por que verificar
Seção intitulada “Por que verificar”A URL do seu webhook é pública. Sem verificar a assinatura, qualquer um que descubra a URL pode mandar eventos falsos — uma “mensagem recebida” inventada, um “pagamento” que nunca aconteceu. A assinatura prova que o corpo veio do Messajo, com o seu segredo, e que não foi alterado no caminho. O horário dentro dela impede que alguém grave uma entrega e a repita depois.
O cabeçalho
Seção intitulada “O cabeçalho”Cada entrega traz o cabeçalho Messajo-Signature:
Messajo-Signature: t=1762697007,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bdté o horário da assinatura, em segundos Unix. Aparece uma vez só.v1é o HMAC-SHA256 em hexadecimal. Durante a rotação do segredo vêm doisv1, um por segredo ativo: basta um bater.- Ignore esquemas que você não conhece (um
v2=futuro, por exemplo).
O segredo do destino começa com whsec_ e aparece uma vez só, ao criar o destino (no painel ou na resposta de POST /v1/destinations). Depois o painel mostra só os 4 últimos caracteres. Perdeu? Gire o segredo.
Passo a passo
Seção intitulada “Passo a passo”- Leia o corpo cru da requisição, exatamente os bytes que chegaram, antes de qualquer parse de JSON.
- Separe
te osv1do cabeçalho. - Monte a mensagem
${t}.${corpo}— o horário, um ponto e o corpo cru. - Calcule o HMAC-SHA256 dessa mensagem usando como chave o segredo inteiro, com o prefixo
whsec_, em UTF-8. O resultado em hexadecimal minúsculo. - Compare com cada
v1em tempo constante (timingSafeEqual,hmac.compare_digest,hash_equals). Comparação com==vaza informação pelo tempo de resposta. - Recuse se
testiver a mais de 5 minutos do seu relógio, para trás ou para frente.
Assinatura inválida → responda 400 e descarte o evento. Válida → responda 2xx rápido e processe depois (veja Eventos).
Exemplos
Seção intitulada “Exemplos”Os três exemplos não usam biblioteca externa e são testados a cada build contra o assinador do Messajo.
Node.js
Seção intitulada “Node.js”import { createHmac, timingSafeEqual } from "node:crypto";
const TOLERANCE_SECONDS = 300;const DIGITS = /^\d+$/;
/** * Checks the Messajo-Signature header ("t=<unix s>,v1=<hex>[,v1=<hex>…]"). * `rawBody` must be the exact body received, before any JSON parsing. */export function verify( header: string, rawBody: string, secret: string, nowSeconds: number = Math.floor(Date.now() / 1000)): boolean { const timestamps: string[] = []; const signatures: string[] = []; for (const part of header.split(",")) { const [key, value = ""] = part.trim().split("=", 2); if (key === "t") { timestamps.push(value); } else if (key === "v1") { signatures.push(value); } } const [rawTimestamp = ""] = timestamps; if (timestamps.length !== 1 || !DIGITS.test(rawTimestamp)) { return false; } const timestamp = Number(rawTimestamp); if (Math.abs(nowSeconds - timestamp) > TOLERANCE_SECONDS) { return false; } const expected = Buffer.from( createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex") ); return signatures.some((signature) => { const received = Buffer.from(signature); return ( received.length === expected.length && timingSafeEqual(received, expected) ); });}"""Verify a Messajo webhook signature.
Usage: python3 verify.py <secret> <Messajo-Signature header> < raw_bodyExit code 0 = valid signature, 1 = invalid."""
import hashlibimport hmacimport sysimport time
TOLERANCE_SECONDS = 300
def verify(header: str, raw_body: bytes, secret: str, now: int | None = None) -> bool: """`raw_body` must be the exact bytes received, before any JSON parsing.""" timestamps, signatures = [], [] for part in header.split(","): key, _, value = part.strip().partition("=") if key == "t": timestamps.append(value) elif key == "v1": signatures.append(value) if len(timestamps) != 1 or not (timestamps[0].isascii() and timestamps[0].isdigit()): return False timestamp = int(timestamps[0]) now = int(time.time()) if now is None else now if abs(now - timestamp) > TOLERANCE_SECONDS: return False signed = f"{timestamp}.".encode() + raw_body expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest() return any(hmac.compare_digest(expected, signature) for signature in signatures)
if __name__ == "__main__": secret, header = sys.argv[1], sys.argv[2] sys.exit(0 if verify(header, sys.stdin.buffer.read(), secret) else 1)<?php// Verify a Messajo webhook signature.// Usage: php verify.php <secret> <Messajo-Signature header> < raw_body// Exit code 0 = valid signature, 1 = invalid.
const MESSAJO_TOLERANCE_SECONDS = 300;
// $rawBody must be the exact body received, before json_decode.function messajo_verify(string $header, string $rawBody, string $secret, ?int $now = null): bool{ $timestamps = []; $signatures = []; foreach (explode(',', $header) as $part) { [$key, $value] = array_pad(explode('=', trim($part), 2), 2, ''); if ($key === 't') { $timestamps[] = $value; } elseif ($key === 'v1') { $signatures[] = $value; } } if (count($timestamps) !== 1 || !ctype_digit($timestamps[0])) { return false; } $timestamp = (int) $timestamps[0]; if (abs(($now ?? time()) - $timestamp) > MESSAJO_TOLERANCE_SECONDS) { return false; } $expected = hash_hmac('sha256', "{$timestamp}.{$rawBody}", $secret); foreach ($signatures as $signature) { if (hash_equals($expected, $signature)) { return true; } } return false;}
if (PHP_SAPI === 'cli' && realpath($argv[0]) === __FILE__) { exit(messajo_verify($argv[2], file_get_contents('php://stdin'), $argv[1]) ? 0 : 1);}Como pegar o corpo cru em cada framework:
| Framework | Corpo cru |
|---|---|
| Express | app.post("/webhook", express.raw({ type: "application/json" }), …) e req.body.toString("utf8") |
| Hono | await c.req.text() |
| FastAPI | await request.body() |
| Laravel | $request->getContent() |
Use o corpo cru na verificação e só depois faça o JSON.parse / json.loads / json_decode.
- No nó Webhook, em Options, ligue Raw Body.
- Depois dele, um nó Code (JavaScript) com o código do exemplo Node.js, lendo o cabeçalho
messajo-signaturee o corpo cru do item recebido. - O nó Code só carrega
cryptose o n8n permitir: definaNODE_FUNCTION_ALLOW_BUILTIN=cryptono ambiente do n8n e reinicie. - Assinatura inválida → pare o fluxo (nó Stop and Error ou um IF).
Girar o segredo sem parar
Seção intitulada “Girar o segredo sem parar”-
No painel, abra o destino e clique em Girar segredo, ou chame
POST /v1/destinations/{id}/rotate-secret. O Messajo gera um segredo novo e o mostra uma vez só. -
Escolha a janela de convivência: de 0 a 72 horas, padrão 24 horas (
keep_previous_hoursna API). Durante a janela os dois valem e cada entrega vem com doisv1, primeiro o do segredo novo, depois o do antigo:Messajo-Signature: t=1762697007,v1=<hmac com o novo>,v1=<hmac com o antigo> -
Troque o segredo na sua aplicação dentro da janela. Como basta um
v1bater, não há momento em que eventos sejam recusados. O fim da janela aparece no destino (previous_secret_expires_atna API). -
Passada a janela, o segredo antigo deixa de assinar e as entregas voltam a ter um
v1só.
Com janela 0 o antigo para de assinar na hora: use só quando o segredo vazou. Girar de novo dentro da janela descarta o antigo anterior: valem só o segredo atual e o que acabou de ser substituído.
Erros comuns
Seção intitulada “Erros comuns”- JSON re-serializado. O framework fez parse do corpo e você assinou
JSON.stringify(req.body). Espaços, ordem de chaves e escape de acentos mudam e o HMAC não bate. Use o corpo cru. - Relógio errado. Servidor sem NTP fica fora dos 5 minutos e recusa tudo como antigo. Sincronize o relógio.
- Segredo com espaço. Espaço ou quebra de linha no fim do segredo copiado (comum em
.env). Confira o tamanho e remova espaços. - Segredo sem o prefixo. A chave do HMAC é o segredo inteiro, com
whsec_. - Corpo decodificado com outro charset. Leia os bytes como UTF-8; acentos e emojis fazem diferença.