Pular para o conteúdo

Webhooks

Verificar a assinatura

Como confirmar que um webhook veio mesmo do Messajo, com exemplos em várias linguagens.

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.

Cada entrega traz o cabeçalho Messajo-Signature:

Messajo-Signature: t=1762697007,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
  • t é 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 dois v1, 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.

  1. Leia o corpo cru da requisição, exatamente os bytes que chegaram, antes de qualquer parse de JSON.
  2. Separe t e os v1 do cabeçalho.
  3. Monte a mensagem ${t}.${corpo} — o horário, um ponto e o corpo cru.
  4. 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.
  5. Compare com cada v1 em tempo constante (timingSafeEqual, hmac.compare_digest, hash_equals). Comparação com == vaza informação pelo tempo de resposta.
  6. Recuse se t estiver 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).

Os três exemplos não usam biblioteca externa e são testados a cada build contra o assinador do Messajo.

verify.ts
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.py
"""Verify a Messajo webhook signature.
Usage: python3 verify.py <secret> <Messajo-Signature header> < raw_body
Exit code 0 = valid signature, 1 = invalid.
"""
import hashlib
import hmac
import sys
import 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)
verify.php
<?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.

  1. No nó Webhook, em Options, ligue Raw Body.
  2. Depois dele, um nó Code (JavaScript) com o código do exemplo Node.js, lendo o cabeçalho messajo-signature e o corpo cru do item recebido.
  3. O nó Code só carrega crypto se o n8n permitir: defina NODE_FUNCTION_ALLOW_BUILTIN=crypto no ambiente do n8n e reinicie.
  4. Assinatura inválida → pare o fluxo (nó Stop and Error ou um IF).
  1. 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ó.

  2. Escolha a janela de convivência: de 0 a 72 horas, padrão 24 horas (keep_previous_hours na API). Durante a janela os dois valem e cada entrega vem com dois v1, primeiro o do segredo novo, depois o do antigo:

    Messajo-Signature: t=1762697007,v1=<hmac com o novo>,v1=<hmac com o antigo>
  3. Troque o segredo na sua aplicação dentro da janela. Como basta um v1 bater, não há momento em que eventos sejam recusados. O fim da janela aparece no destino (previous_secret_expires_at na API).

  4. Passada a janela, o segredo antigo deixa de assinar e as entregas voltam a ter um v1 só.

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.

  • 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.