Recibir eventos de Masnet en Boomi

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 proceso

1. Cree un proceso cuyo inicio sea un conector de servidor web de Boomi en modo de escucha (Web Services Server) y publique su URL con TLS en un nombre DNS público (https, puerto 443 u 8443). Esa URL se escribe en Dirección del destino (https) en Masnet.
2. Boomi puede exponer las cabeceras HTTP como propiedades dinámicas del documento. Los nombres exactos de esas propiedades no se publican aquí porque no se pudieron verificar con la documentación disponible: ejecute el evento de prueba y consulte las propiedades del documento en el seguimiento del proceso para identificar las de webhook-id, webhook-timestamp y webhook-signature.
3. Agregue un paso de scripting personalizado antes de cualquier mapa o conversión, de modo que el script reciba el cuerpo original.
4. Guarde el secreto de firma como propiedad de proceso cifrada o extensión protegida, no en el script.

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 script debe ejecutar estos pasos, en este orden:

1. Leer webhook-id, webhook-timestamp y webhook-signature. Rechazar si falta alguno o si el valor absoluto de la diferencia con la hora actual supera 300 segundos.
2. Decodificar en base64 el secreto sin el prefijo whsec_ para obtener la clave.
3. Calcular HMAC-SHA256 con esa clave sobre webhook-id + . + webhook-timestamp + . + los bytes del cuerpo.
4. Separar webhook-signature por espacios; para cada parte v1,<base64>, comparar en tiempo constante con el valor calculado. Basta que una coincida.

La implementación Java de referencia, ejecutada contra los vectores de prueba de esta documentación, está en verificación en Java.

Respuesta

Responda 200 si la firma es válida. Si no lo es, devuelva un estado 401; Masnet lo reintentará. Si el procesamiento posterior es largo, desacóplelo para responder antes de 15 segundos.

Prueba con el evento de prueba

1. Despliegue el proceso en su Atom.
2. En Masnet, seleccione Probar destino y Enviar prueba.
3. Compruebe en el seguimiento del proceso que el documento llegó con la cabecera Masnet-Event-Type: com.masnet.integration.test.v1.

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: