Skip to main content

​
Descripción General

Los eventos de webhook de análisis de riesgo le permiten recibir notificaciones en tiempo real cuando se ejecuta una matriz de riesgo sobre una entidad (persona o empresa) o sobre una transacción. Gu1 envía solicitudes HTTP POST a su endpoint de webhook configurado cada vez que finaliza un análisis de riesgo, para que pueda sincronizar puntuaciones de riesgo con sistemas externos, alimentar herramientas de BI o activar flujos de trabajo.

​
¿Por Qué Usar Eventos de Análisis de Riesgo?

Sincronización de Riesgo

Mantenga sistemas externos actualizados con las últimas puntuaciones de riesgo

Automatización de Workflows

Active procesos cuando finalice el análisis (p. ej. escalamiento, reportes)

Registro de Auditoría

Registre cada ejecución de matriz de riesgo para cumplimiento

Analíticas y BI

Alimente resultados de riesgo en dashboards e informes

​
Eventos Disponibles

Tipo de EventoDescripciónCuándo se Activa
risk_analysis_entity_executedMatriz de riesgo ejecutada sobre persona o empresaCuando se ejecuta una matriz de riesgo sobre una persona o empresa (ejecución manual o automática: entity_created, enrichment_completed, etc.)
risk_analysis_transaction_executedMatriz de riesgo ejecutada sobre transacciónCuando se ejecuta una matriz de riesgo sobre una transacción (p. ej. al crear/actualizar con reglas aplicadas)
Ubicación del disparador: apps/api/src/services/rules-execution.service.ts (tras la ejecución correcta del motor de reglas).

​
Estructura del Payload del Evento

Todos los webhooks de análisis de riesgo siguen esta estructura: 
{
  "event": "risk_analysis_entity_executed",
  "timestamp": "2025-02-19T14:00:00.000Z",
  "organizationId": "org-uuid",
  "payload": {
    "entity": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "type": "person",
      "name": "John Doe",
      "taxId": "123-45-6789",
      "externalId": "customer_abc123"
    },
    "rulesExecutionSummary": {
      "rulesHit": [],
      "rulesNoHit": [],
      "totalScore": 25,
      "scoreResult": { "rawScore": 25, "normalizedScore": 35, "label": { "name": "Medio", "range": "30-80" } },
      "riskMatrixName": "Matriz de entidades por defecto",
      "executionTimeMs": 120,
      "trigger": "entity_created",
      "matchedRulesCount": 0
    },
    "riskScore": 25,
    "totalRules": 10,
    "successfulRules": 10,
    "executionTimeMs": 120,
    "triggerEvent": "entity_created",
    "riskMatrixName": "Default Entity Matrix",
    "auditId": "audit-uuid"
  }
}

​
Campos Principales del Payload

​
entity
object
La entidad analizada: id, type (person | company | transaction), name, taxId, externalId
​
rulesExecutionSummary
object
Resumen de ejecución de reglas: rulesHit, rulesNoHit, actionsExecuted (opcional), totalScore, scoreResult, riskMatrixName, executionTimeMs, trigger, matchedRulesCount. Puede ser null. Estructura completa y ejemplo: Resumen de Ejecución de Reglas.
​
riskScore
number
Puntuación de riesgo final de la ejecución de la matriz de riesgo
​
totalRules
number
Número total de reglas evaluadas
​
successfulRules
number
Número de reglas que se ejecutaron correctamente
​
executionTimeMs
number
Tiempo de ejecución del análisis de riesgo en milisegundos
​
triggerEvent
string
Qué disparó el análisis (p. ej. entity_created, enrichment_completed, manual)
​
riskMatrixName
string
Nombre de la matriz de riesgo ejecutada, o null
​
auditId
string
ID del registro de auditoría del análisis de riesgo, o null

​
risk_analysis_entity_executed

Se envía cuando se ejecuta una matriz de riesgo sobre una entidad de tipo persona o empresa. Cuándo se dispara:
  • Análisis de riesgo manual desde el dashboard
  • Disparo automático al crear una entidad (cuando se aplican reglas)
  • Tras completar un enriquecimiento (cuando está configurado para ejecutar reglas)
  • Otros disparos automáticos que ejecutan el motor de reglas sobre una entidad
Payload: Misma estructura que arriba; entity.type es person o company.

​
risk_analysis_transaction_executed

Se envía cuando se ejecuta una matriz de riesgo sobre una transacción. Cuándo se dispara:
  • Transacción creada o actualizada con reglas aplicadas
  • Cualquier flujo que ejecute el motor de reglas sobre una transacción
Payload: Misma estructura; entity.type es transaction. En transacciones, entity.name suele ser el ID externo o identificador de la transacción.

​
Ejemplo de Código

​
Node.js – Manejo de Eventos de Análisis de Riesgo

app.post('/webhooks/gu1', async (req, res) => {
  try {
    const signature = req.headers['x-webhook-signature'];
    const rawBody = req.rawBody || JSON.stringify(req.body);
    if (!verifySignature(rawBody, signature, process.env.GU1_WEBHOOK_SECRET)) {
      return res.status(401).json({ error: 'Firma inválida' });
    }

    const { event, payload } = req.body;

    if (event === 'risk_analysis_entity_executed' || event === 'risk_analysis_transaction_executed') {
      await handleRiskAnalysisCompleted(event, payload);
    }

    res.status(200).json({ success: true });
  } catch (error) {
    console.error('Error en webhook:', error);
    res.status(500).json({ error: error.message });
  }
});

async function handleRiskAnalysisCompleted(event, payload) {
  const { entity, riskScore, riskMatrixName, auditId, triggerEvent } = payload;

  // Sincronizar puntuación de riesgo en su sistema
  await db.entities.update({
    where: { externalId: entity.externalId },
    data: {
      riskScore,
      riskMatrixName,
      lastRiskAnalysisAt: new Date(),
      lastTriggerEvent: triggerEvent,
    },
  });

  // Opcional: activar flujos para alto riesgo
  if (riskScore >= 75) {
    await compliance.queueReview(entity.id, riskScore, auditId);
  }
}

​
Mejores Prácticas

  • Idempotencia: Use entity.id + auditId (o timestamp) para no procesar el mismo análisis dos veces.
  • Verificar firma: Siempre valide X-Webhook-Signature como se describe en la guía de seguridad.
  • Responder rápido: Devuelva 200 en cuanto reciba el webhook; procese de forma asíncrona si es necesario.

​
Próximos Pasos

Eventos de Entidades

Maneje eventos del ciclo de vida de entidades

Eventos de Transacciones

Procese webhooks de transacciones

Seguridad de Webhooks

Proteja sus endpoints de webhook

Configuración

Configure ajustes de webhook