Webhooks
Verificar la firma
Cómo confirmar que un webhook realmente vino de Messajo, con ejemplos en varios lenguajes.
Por qué verificar
Sección titulada «Por qué verificar»La URL de tu webhook es pública. Sin verificar la firma, cualquiera que descubra la URL puede enviar eventos falsos — un “mensaje recibido” inventado, un “pago” que nunca ocurrió. La firma prueba que el cuerpo vino de Messajo, con tu secreto, y que no se alteró en el camino. La hora dentro de ella impide que alguien grabe una entrega y la repita después.
La cabecera
Sección titulada «La cabecera»Cada entrega trae la cabecera Messajo-Signature:
Messajo-Signature: t=1762697007,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bdtes la hora de la firma, en segundos Unix. Aparece una sola vez.v1es el HMAC-SHA256 en hexadecimal. Durante la rotación del secreto llegan dosv1, uno por secreto activo: basta con que uno coincida.- Ignora los esquemas que no conoces (un
v2=futuro, por ejemplo).
El secreto del destino empieza con whsec_ y aparece una sola vez, al crear el destino (en el panel o en la respuesta de POST /v1/destinations). Después el panel muestra solo los últimos 4 caracteres. ¿Lo perdiste? Rota el secreto.
Paso a paso
Sección titulada «Paso a paso»- Lee el cuerpo crudo de la petición, exactamente los bytes que llegaron, antes de cualquier parseo de JSON.
- Separa
ty losv1de la cabecera. - Arma el mensaje
${t}.${cuerpo}— la hora, un punto y el cuerpo crudo. - Calcula el HMAC-SHA256 de ese mensaje usando como clave el secreto entero, con el prefijo
whsec_, en UTF-8. El resultado en hexadecimal en minúsculas. - Compara con cada
v1en tiempo constante (timingSafeEqual,hmac.compare_digest,hash_equals). Comparar con==filtra información por el tiempo de respuesta. - Rechaza si
testá a más de 5 minutos de tu reloj, hacia atrás o hacia adelante.
Firma inválida → responde 400 y descarta el evento. Válida → responde 2xx rápido y procesa después (mira Eventos).
Ejemplos
Sección titulada «Ejemplos»Los tres ejemplos no usan bibliotecas externas y se prueban en cada build contra el firmador de Messajo.
Node.js
Sección titulada «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);}Cómo obtener el cuerpo crudo en cada framework:
| Framework | Cuerpo crudo |
|---|---|
| Express | app.post("/webhook", express.raw({ type: "application/json" }), …) y req.body.toString("utf8") |
| Hono | await c.req.text() |
| FastAPI | await request.body() |
| Laravel | $request->getContent() |
Usa el cuerpo crudo en la verificación y solo después haz el JSON.parse / json.loads / json_decode.
- En el nodo Webhook, en Options, activa Raw Body.
- Después, un nodo Code (JavaScript) con el código del ejemplo de Node.js, leyendo la cabecera
messajo-signaturey el cuerpo crudo del ítem recibido. - El nodo Code solo carga
cryptosi n8n lo permite: defineNODE_FUNCTION_ALLOW_BUILTIN=cryptoen el entorno de n8n y reinícialo. - Firma inválida → detén el flujo (nodo Stop and Error o un IF).
Rotar el secreto sin interrupciones
Sección titulada «Rotar el secreto sin interrupciones»-
En el panel, abre el destino y haz clic en Rotar secreto, o llama a
POST /v1/destinations/{id}/rotate-secret. Messajo genera un secreto nuevo y lo muestra una sola vez. -
Elige la ventana de convivencia: de 0 a 72 horas, 24 horas por defecto (
keep_previous_hoursen la API). Durante la ventana los dos valen y cada entrega llega con dosv1, primero el del secreto nuevo, después el del viejo:Messajo-Signature: t=1762697007,v1=<hmac con el nuevo>,v1=<hmac con el viejo> -
Cambia el secreto en tu aplicación dentro de la ventana. Como basta con que un
v1coincida, no hay momento en que se rechacen eventos. El fin de la ventana aparece en el destino (previous_secret_expires_aten la API). -
Pasada la ventana, el secreto viejo deja de firmar y las entregas vuelven a tener un solo
v1.
Con ventana 0 el viejo deja de firmar en el acto: úsala solo cuando el secreto se filtró. Rotar de nuevo dentro de la ventana descarta el más antiguo: valen solo el secreto actual y el que acaba de reemplazar.
Errores comunes
Sección titulada «Errores comunes»- JSON re-serializado. El framework parseó el cuerpo y firmaste
JSON.stringify(req.body). Espacios, orden de claves y escape de acentos cambian y el HMAC no coincide. Usa el cuerpo crudo. - Reloj equivocado. Un servidor sin NTP se sale de los 5 minutos y rechaza todo como viejo. Sincroniza el reloj.
- Secreto con espacio. Un espacio o salto de línea al final del secreto copiado (común en
.env). Revisa el largo y quita los espacios. - Secreto sin el prefijo. La clave del HMAC es el secreto entero, con
whsec_. - Cuerpo decodificado con otro charset. Lee los bytes como UTF-8; acentos y emojis importan.