Llevar eventos de Masnet a HubSpot con un intermediario

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.

Arquitectura

1. Elija el intermediario y configure su recepción con la guía correspondiente: n8n, Make, Zapier, MuleSoft o una de las guías de verificación en código.
2. Escriba la URL del intermediario en Dirección del destino (https) en Masnet.
3. En el intermediario, verifique la firma y solo entonces llame a HubSpot.

Escritura en HubSpot

La API de CRM v3 crea un contacto con POST https://api.hubapi.com/crm/v3/objects/contacts y un cuerpo JSON con properties (y associations); responde 201 con el objeto creado. Otros objetos siguen el mismo patrón en la referencia de la API de HubSpot. La autenticación se configura según la documentación de autenticación de HubSpot.

{
  "properties": {
    "email": "[email protected]",
    "firstname": "Ejemplo",
    "lastname": "Apellido"
  },
  "associations": []
}

Los eventos de Masnet tratan de contratos, garantías, licitaciones y otros objetos de gestión, no de contactos. Defina en HubSpot propiedades personalizadas para guardar, por ejemplo, el identificador de Masnet y el código de contrato, y mapee desde data.object. Los nombres de las propiedades son una decisión de su organización.

Respuesta

El intermediario responde 2xx a Masnet tras verificar la firma y encolar el trabajo. La llamada a HubSpot debe hacerse de forma asíncrona.

Prueba con el evento de prueba

1. Envíe la prueba desde Masnet con Probar destino y Enviar prueba.
2. Compruebe que el intermediario verifica la firma y no escribe en HubSpot para 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: