Recibir eventos de Masnet en Azure Logic Apps y Power Automate

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. En Logic Apps, cree un flujo con el disparador Request (llamado «When a HTTP request is received» en la documentación). Power Automate ofrece un disparador equivalente de solicitud HTTP.
2. Deje el método en POST (es el valor por defecto) y el esquema JSON del cuerpo vacío, o genérelo con un evento de ejemplo de Eventos.
3. Guarde el flujo. El cuadro HTTP URL muestra la URL de devolución de llamada, con parámetros de consulta que incluyen sig= (firma de acceso compartido).
4. Copie esa URL completa y escríbala en Dirección del destino (https) en Masnet. Masnet admite cadenas de consulta, cifra la URL completa como un secreto, muestra en la interfaz solo el host y la ruta con la consulta enmascarada y no la registra en logs ni en métricas.
5. Trate la URL como una credencial: no la pegue en tickets ni en repositorios. Si se expone, regenere la clave de acceso del flujo en Azure y actualice la dirección del destino en Masnet.

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.

El diseñador de Logic Apps interpreta el cuerpo JSON antes de que usted pueda acceder a él, de modo que reconstruirlo con una expresión puede producir bytes distintos de los firmados. Para evitarlo, llame desde el flujo a una función de Azure (disparador HTTP) o a un servicio propio que reciba el cuerpo sin interpretar, reenviando las tres cabeceras webhook-*, y que use la verificación de Node.js, Python, Java o C#.

Con el formato CloudEvents estructurado el tipo de contenido es application/cloudevents+json; según la documentación de Logic Apps, un contenido que no es application/json se trata como una unidad binaria. Compruebe en su flujo cuál de los dos formatos le entrega los bytes sin alterar.

Expresiones útiles del disparador (ilustrativas):

// Idempotency key (Request trigger outputs)
triggerOutputs()['headers']['webhook-id']

// Event type
triggerOutputs()['headers']['masnet-event-type']

// Event data (the JSON body, parsed by the designer)
triggerBody()?['data']?['object']

Respuesta

Si el flujo no incluye una acción Response, el punto de conexión responde de inmediato 202 Accepted, que Masnet considera éxito. Si agrega una acción Response, use el código 200 o 202 tras verificar la firma, y 401 si es inválida; Azure no admite códigos 3xx en esa acción. Si la respuesta tarda más que el límite de espera de Azure, el llamante recibe 408, y Masnet corta de todos modos a los 15 segundos.

Prueba con el evento de prueba

1. En Masnet, seleccione Probar destino y Enviar prueba.
2. En el historial de ejecuciones del flujo, abra la ejecución y compruebe que masnet-event-type vale com.masnet.integration.test.v1.
3. Active el destino solo después de una prueba exitosa.

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: