Recibir eventos de Masnet en Make

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 escenario

1. Cree un escenario con el módulo Custom webhook y agregue un webhook. Copie su URL a Dirección del destino (https) en Masnet; la URL del webhook es una credencial.
2. En la configuración avanzada del módulo, active Get request headers para leer webhook-id, webhook-timestamp y webhook-signature.
3. El módulo tiene la opción JSON pass-through, que entrega el JSON como una cadena de texto en lugar de campos separados.
4. Para responder, agregue un módulo Webhook response con Status 200. Sin ese módulo, Make responde 200 «Accepted» cuando el evento queda en cola.

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.

• Lo que se verificó en la documentación de Make: existen la opción de cabeceras de la solicitud, la opción de entrega del JSON como texto y el módulo de respuesta.
• Lo que no se pudo verificar: que el texto entregado sea idéntico, byte a byte, al cuerpo recibido, y que Make disponga de una función de HMAC-SHA256 con clave en base64. No lo asuma.
• Cómo proceder: habilite una prueba con el evento de prueba y compare la firma calculada con la recibida. Si no coincide, o si no puede calcular el HMAC, delegue la verificación a un servicio propio con la guía de Node.js o Python y deje que Make solo reciba eventos ya verificados.
• Mientras tanto: configure una credencial adicional del destino de Masnet (por ejemplo, Cabecera con clave de API) y exíjala en el escenario si Make lo permite. Note que Make reserva la cabecera x-make-apikey y su valor no llega al escenario.

Respuesta

Si agrega el módulo Webhook response, Make puede tardar hasta 180 segundos en responder cuando el escenario no termina, mucho más que los 15 segundos de Masnet. Mantenga el escenario corto o responda con el módulo lo antes posible.

Prueba con el evento de prueba

1. Ejecute el escenario en modo de espera de datos.
2. En Masnet, seleccione Probar destino y Enviar prueba.
3. Make aprende la estructura de datos con esa primera solicitud; confirme que reconoce data y id.

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: