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

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:

Campos Principales del Payload

object
La entidad analizada: id, type (person | company | transaction), name, taxId, externalId
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.
number
Puntuación de riesgo final de la ejecución de la matriz de riesgo
number
Número total de reglas evaluadas
number
Número de reglas que se ejecutaron correctamente
number
Tiempo de ejecución del análisis de riesgo en milisegundos
string
Qué disparó el análisis (p. ej. entity_created, enrichment_completed, manual)
string
Nombre de la matriz de riesgo ejecutada, o null
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

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