Recibir eventos de Masnet en n8n

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.

Configuración del flujo

1. Agregue un nodo Webhook con HTTP Method POST y una Path propia. Use la Production URL del nodo (no la de prueba) en Dirección del destino (https) en Masnet; el flujo debe estar activo.
2. En Options, agregue Raw Body. Según la documentación de n8n, hace que el nodo reciba los datos en formato sin procesar.
3. En Respond, elija Immediately para responder de inmediato, o Using 'Respond to Webhook' Node si debe responder 401 ante una firma inválida.
4. Guarde el secreto de firma como variable de entorno de n8n o credencial, no dentro del flujo.

Verificación de la firma

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.

Agregue un nodo Code después del Webhook. El ejemplo es ilustrativo: el nombre de la propiedad binaria con el cuerpo, la forma de leer variables de entorno y la autorización para cargar el módulo crypto dependen de su versión y de su configuración de n8n; confírmelos con el evento de prueba.

// Code node ("Run Once for All Items"), illustrative.
// Requires the Webhook node option "Raw Body" and permission to load the built-in module "crypto".
const crypto = require('crypto');
const item = $input.first();
const headers = item.json.headers;
const raw = await this.helpers.getBinaryDataBuffer(0, 'data'); // confirm the binary property name in the node output
const secret = $env.MASNET_WEBHOOK_SECRET;                      // keep the secret outside the workflow

const id = headers['webhook-id'];
const ts = headers['webhook-timestamp'];
const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
const expected = crypto.createHmac('sha256', key).update(id + '.' + ts + '.').update(raw).digest();
const fresh = Math.abs(Date.now() / 1000 - Number(ts)) <= 300;
const valid = fresh && String(headers['webhook-signature']).split(' ').some((part) => {
  const [version, value] = part.split(',');
  const given = Buffer.from(value || '', 'base64');
  return version === 'v1' && given.length === expected.length && crypto.timingSafeEqual(given, expected);
});
if (!valid) throw new Error('Invalid Masnet webhook signature');
return [{ json: { verified: true, eventId: id } }];

Si su instalación no puede obtener los bytes originales, no verifique reconstruyendo el JSON: reserializar puede cambiar los bytes. Use en su lugar un servicio propio con la guía de Node.js.

Respuesta

Con Immediately, n8n responde antes de ejecutar el resto; la verificación fallida no se refleja en la respuesta. Para devolver 401 ante una firma inválida use Using 'Respond to Webhook' Node. Termine siempre antes de 15 segundos.

Prueba con el evento de prueba

1. Active el flujo.
2. En Masnet, seleccione Probar destino y Enviar prueba.
3. En las ejecuciones de n8n, compruebe que el nodo Code termina sin error.

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: