Verificar la firma de Masnet en Node.js

Requisitos en Masnet

Antes de configurar el sistema receptor, prepare el destino en Masnet. Los pasos son los mismos para todos los sistemas.

1. Abra Empresa › Integraciones, vaya a la pestaña Destinos y seleccione Nuevo destino. Si la integración aún no tiene datos autorizados, Masnet le pedirá autorizarlos primero.
2. En Dirección del destino (https) escriba la URL pública del receptor. Debe ser https, puerto 443 u 8443 y un nombre DNS público: no se admiten usuario en la URL, fragmento, direcciones IP ni nombres internos. Se admite una cadena de consulta; Masnet trata la URL completa como una credencial.
3. En Formato elija JSON estándar (application/json) o CloudEvents estructurado (application/cloudevents+json). El contenido del evento es el mismo; consulte Webhooks.
4. Seleccione Crear destino. Masnet muestra el secreto de firma (whsec_…) una sola vez. Guárdelo de inmediato en el almacén de secretos del receptor; no podrá consultarlo después.
5. Seleccione Probar destino y luego Enviar prueba. La integración solo se activa con una prueba exitosa; después use Activar destino.

Datos que necesita el verificador

• El secreto de firma (whsec_…) del destino, guardado fuera del código.
• El cuerpo exacto recibido, sin interpretar. En Express use express.raw({ type: '*/*' }) en la ruta del webhook, de modo que req.body sea un Buffer; no use express.json() antes de verificar.
• Las cabeceras webhook-id, webhook-timestamp y webhook-signature.
• Una tolerancia de reloj de 5 minutos, que es la que aplican las bibliotecas de Standard Webhooks y la recomendada para el receptor.

La firma es v1, seguido de base64(HMAC-SHA256) calculado con la clave binaria que resulta de decodificar en base64 lo que sigue a whsec_, sobre los bytes webhook-id + . + webhook-timestamp + . + cuerpo exacto. Verifique siempre sobre los bytes recibidos, antes de interpretar el JSON.

Con la biblioteca standardwebhooks

Instale standardwebhooks desde npm. La biblioteca valida la tolerancia de 5 minutos y las firmas múltiples.

// npm install standardwebhooks
import { Webhook } from 'standardwebhooks'

/**
 * `rawBody` is the unparsed request body (string or Buffer); `headers` holds webhook-id,
 * webhook-timestamp and webhook-signature. The library enforces a 5 minute tolerance.
 */
export function verify({ secret, headers, rawBody }) {
  try {
    new Webhook(secret).verify(rawBody, headers)
    return true
  } catch {
    return false
  }
}

Sin dependencias

La función compara en tiempo constante y acepta cualquiera de las firmas del encabezado.

import { createHmac, timingSafeEqual } from 'node:crypto'

/**
 * Verifies a Masnet webhook with node:crypto only.
 * `rawBody` must be the exact bytes received (Buffer or string), before any JSON parsing.
 */
export function verify({ secret, headers, rawBody, now = Date.now() / 1000, tolerance = 300 }) {
  const id = headers['webhook-id']
  const timestamp = headers['webhook-timestamp']
  const signatures = headers['webhook-signature']
  if (!id || !signatures || !/^\d+$/.test(timestamp ?? '')) return false
  if (Math.abs(now - Number(timestamp)) > tolerance) return false

  const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64')
  const expected = createHmac('sha256', key).update(`${id}.${timestamp}.`).update(rawBody).digest()

  // During a rotation the header carries two signatures separated by a space; any match is valid.
  return signatures.split(' ').some((part) => {
    const [version, value] = part.split(',')
    if (version !== 'v1' || !value) return false
    const given = Buffer.from(value, 'base64')
    return given.length === expected.length && timingSafeEqual(given, expected)
  })
}

Operación: duplicados y orden

• Idempotencia. webhook-id identifica el evento y se conserva en los reintentos y los reenvíos. Registre los identificadores ya procesados y descarte los repetidos con una respuesta 2xx.
• Orden. Cada recurso (subject) lleva un sequence creciente. Descarte un evento cuyo sequence sea menor o igual al último que aplicó para ese subject. Los eventos de recursos distintos no tienen orden entre sí.
• Reintentos. Masnet reintenta cualquier respuesta distinta de 2xx durante un máximo de 72 horas; el calendario completo está en Webhooks.
• Rotación del secreto. Al rotar con superposición, el secreto anterior sigue vigente 24 horas y webhook-signature trae dos firmas v1,… separadas por un espacio. Acepte el evento si cualquiera coincide.

Diagnóstico

Masnet registra el código de respuesta de cada intento en el historial de entregas. Estos son los efectos de cada respuesta del receptor: