Recibir eventos de Masnet en MuleSoft

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 de la aplicación

1. Cree un flujo cuyo origen sea un HTTP Listener con una ruta estática, por ejemplo /masnet/eventos, y publíquelo con TLS (https, puerto 443 u 8443) en un nombre DNS público.
2. En el listener, el cuerpo HTTP se convierte en el *payload* y las cabeceras en attributes.headers (según la documentación del conector). Masnet envía los nombres en minúsculas: webhook-id, webhook-timestamp y webhook-signature.
3. No coloque ninguna transformación antes de la verificación. Si el payload se reserializa, los bytes cambian y la firma deja de coincidir.
4. Guarde el secreto de firma en una propiedad segura de la aplicación, no en el código.

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.

Una opción es llamar a una clase Java desde el flujo con la operación de invocación estática del módulo Java, pasando el secreto, las cabeceras, el payload como bytes, la hora actual y la tolerancia (300 segundos). La clase siguiente es la versión sin dependencias; devuelve true o false.

import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.util.Base64;
import java.util.Map;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

/** Verifies a Masnet webhook with the JDK only. `rawBody` is the exact bytes received. */
public final class JavaManual {
    public static boolean verify(String secret, Map<String, String> headers, byte[] rawBody, long nowSeconds, long tolerance) {
        String id = headers.get("webhook-id");
        String timestamp = headers.get("webhook-timestamp");
        String signatures = headers.get("webhook-signature");
        if (id == null || signatures == null || timestamp == null || !timestamp.matches("\\d+")) return false;
        if (Math.abs(nowSeconds - Long.parseLong(timestamp)) > tolerance) return false;
        try {
            byte[] key = Base64.getDecoder().decode(secret.replaceFirst("^whsec_", ""));
            Mac mac = Mac.getInstance("HmacSHA256");
            mac.init(new SecretKeySpec(key, "HmacSHA256"));
            mac.update((id + "." + timestamp + ".").getBytes(StandardCharsets.UTF_8));
            byte[] expected = mac.doFinal(rawBody);
            // During a rotation the header carries two signatures separated by a space; any match is valid.
            for (String part : signatures.split(" ")) {
                String[] pair = part.split(",", 2);
                if (pair.length != 2 || !pair[0].equals("v1")) continue;
                try {
                    if (MessageDigest.isEqual(Base64.getDecoder().decode(pair[1]), expected)) return true;
                } catch (IllegalArgumentException malformed) {
                    // ignore a malformed entry and keep looking
                }
            }
        } catch (Exception e) {
            return false;
        }
        return false;
    }
}

Respuesta

Si la verificación es correcta, responda 200 (es el estado por defecto de un flujo exitoso). Si es inválida, configure en la pestaña Responses del listener un estado 401 con un cuerpo breve; Masnet lo tratará como fallo reintentable. Procese el evento en otro flujo (por ejemplo, con una cola) para no exceder 15 segundos.

Prueba con el evento de prueba

1. Despliegue la aplicación.
2. En Masnet, seleccione Probar destino y Enviar prueba.
3. Revise el registro de la aplicación: debe constar un evento con Masnet-Event-Type: com.masnet.integration.test.v1 y verificación correcta.

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: