> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Eventos de Webhook de Análisis de Riesgo

> Reciba notificaciones en tiempo real cuando finalice un análisis de riesgo (ejecución de matriz de riesgo) — con eventos webhook de gu1 para integración.

## 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?

<CardGroup cols={2}>
  <Card title="Sincronización de Riesgo" icon="chart-line">
    Mantenga sistemas externos actualizados con las últimas puntuaciones de riesgo
  </Card>

  <Card title="Automatización de Workflows" icon="robot">
    Active procesos cuando finalice el análisis (p. ej. escalamiento, reportes)
  </Card>

  <Card title="Registro de Auditoría" icon="clipboard-list">
    Registre cada ejecución de matriz de riesgo para cumplimiento
  </Card>

  <Card title="Analíticas y BI" icon="database">
    Alimente resultados de riesgo en dashboards e informes
  </Card>
</CardGroup>

## Eventos Disponibles

| Tipo de Evento                       | Descripción                                        | Cuándo se Activa                                                                                                                                         |
| ------------------------------------ | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `risk_analysis_entity_executed`      | Matriz de riesgo ejecutada sobre persona o empresa | Cuando 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_executed` | Matriz de riesgo ejecutada sobre transacción       | Cuando 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:

```json theme={null}
{
  "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

<ResponseField name="entity" type="object">
  La entidad analizada: `id`, `type` (person | company | transaction), `name`, `taxId`, `externalId`
</ResponseField>

<ResponseField name="rulesExecutionSummary" type="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](/es/api-reference/rules-execution-summary).
</ResponseField>

<ResponseField name="riskScore" type="number">
  Puntuación de riesgo final de la ejecución de la matriz de riesgo
</ResponseField>

<ResponseField name="totalRules" type="number">
  Número total de reglas evaluadas
</ResponseField>

<ResponseField name="successfulRules" type="number">
  Número de reglas que se ejecutaron correctamente
</ResponseField>

<ResponseField name="executionTimeMs" type="number">
  Tiempo de ejecución del análisis de riesgo en milisegundos
</ResponseField>

<ResponseField name="triggerEvent" type="string">
  Qué disparó el análisis (p. ej. `entity_created`, `enrichment_completed`, `manual`)
</ResponseField>

<ResponseField name="riskMatrixName" type="string">
  Nombre de la matriz de riesgo ejecutada, o null
</ResponseField>

<ResponseField name="auditId" type="string">
  ID del registro de auditoría del análisis de riesgo, o null
</ResponseField>

## 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

```javascript theme={null}
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](/es/webhooks/security).
* **Responder rápido**: Devuelva 200 en cuanto reciba el webhook; procese de forma asíncrona si es necesario.

## Próximos Pasos

<CardGroup cols={2}>
  <Card title="Eventos de Entidades" icon="user" href="/es/webhooks/events/entity-events">
    Maneje eventos del ciclo de vida de entidades
  </Card>

  <Card title="Eventos de Transacciones" icon="credit-card" href="/es/webhooks/events/transaction-events">
    Procese webhooks de transacciones
  </Card>

  <Card title="Seguridad de Webhooks" icon="shield" href="/es/webhooks/security">
    Proteja sus endpoints de webhook
  </Card>

  <Card title="Configuración" icon="gear" href="/es/webhooks/configuration">
    Configure ajustes de webhook
  </Card>
</CardGroup>