title: “Verificar la firma de un webhook” description: “Compare el header Ministrium-Signature con el HMAC-SHA256 del body.” audience: [“developer”] modules: [“api”,“seguridad”] estimated_minutes: 5 last_reviewed: “2026-05-03”

Verificar la firma de un webhook

Sin verificación, cualquiera con su URL pública puede inyectar eventos falsos. La firma evita esto al exigir el secret compartido.

TL;DR

HMAC-SHA256(secret, raw_body) debe igualar el header Ministrium-Signature.

Pasos

1. Lea el body crudo (no parseado a JSON antes). 2. Calcule expected = HMAC-SHA256(secret, raw_body) en hex. 3. Compare expected con Ministrium-Signature usando comparación constante (no ==). 4. Si difieren, responda 401 y descarte el evento. 5. Si coinciden, parsee el body y procese el evento.

Ejemplo en Node.js

const crypto = require("crypto");
const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
const sig = req.headers["ministrium-signature"];
if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig))) {
  return res.status(401).end();
}