Risk Analysis Webhook Events

Overview

Risk analysis webhook events allow you to receive real-time notifications when a risk matrix is executed on an entity (person or company) or on a transaction. Gu1 sends HTTP POST requests to your configured webhook endpoint after each risk analysis completes, so you can sync risk scores with external systems, feed BI tools, or trigger workflows.

Why Use Risk Analysis Events?

Risk Score Sync

Keep external systems updated with the latest risk scores

Workflow Automation

Trigger processes when analysis completes (e.g. escalation, reporting)

Audit Trail

Log every risk matrix execution for compliance

Analytics & BI

Feed risk results into dashboards and reports

Available Events

Event Type	Description	When Triggered
`risk_analysis_entity_executed`	Risk matrix run on person or company	When a risk matrix is executed on a person or company (manual run or automatic: entity_created, enrichment_completed, etc.)
`risk_analysis_transaction_executed`	Risk matrix run on transaction	When a risk matrix is executed on a transaction (e.g. on create/update with rules applied)

Trigger location: apps/api/src/services/rules-execution.service.ts (after successful rules engine execution).

Event Payload Structure

All risk analysis webhooks follow this structure:

{
  "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": "Medium", "range": "30-80" } },
      "riskMatrixName": "Default Entity Matrix",
      "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"
  }
}

Key Payload Fields

object

The entity that was analyzed: id, type (person | company | transaction), name, taxId, externalId

object

Summary of rule execution: rulesHit, rulesNoHit, actionsExecuted (optional), totalScore, scoreResult, riskMatrixName, executionTimeMs, trigger, matchedRulesCount. May be null. Full structure and example: Rules Execution Summary.

number

Final risk score from the risk matrix execution

number

Total number of rules evaluated

number

Number of rules that ran successfully

number

Execution time of the risk analysis in milliseconds

string

What triggered the analysis (e.g. entity_created, enrichment_completed, manual)

string

Name of the risk matrix that was executed, or null

string

ID of the risk analysis audit record, or null

risk_analysis_entity_executed

Sent when a risk matrix is executed on a person or company entity. When it fires:

Manual risk analysis from the dashboard
Automatic trigger on entity creation (when rules are applied)
After enrichment completes (when configured to run rules)
Other automatic triggers that run the rules engine on an entity

Payload: Same structure as above; entity.type is person or company.

risk_analysis_transaction_executed

Sent when a risk matrix is executed on a transaction. When it fires:

Transaction created or updated with rules applied
Any flow that runs the rules engine on a transaction

Payload: Same structure; entity.type is transaction. For transactions, entity.name is typically the transaction external ID or identifier.

Code Example

Node.js – Handling Risk Analysis Events

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: 'Invalid signature' });
    }

    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('Webhook error:', error);
    res.status(500).json({ error: error.message });
  }
});

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

  // Sync risk score to your system
  await db.entities.update({
    where: { externalId: entity.externalId },
    data: {
      riskScore,
      riskMatrixName,
      lastRiskAnalysisAt: new Date(),
      lastTriggerEvent: triggerEvent,
    },
  });

  // Optional: trigger workflows for high risk
  if (riskScore >= 75) {
    await compliance.queueReview(entity.id, riskScore, auditId);
  }
}

Best Practices

Idempotency: Use entity.id + auditId (or timestamp) to avoid processing the same analysis twice.
Verify signature: Always validate X-Webhook-Signature as described in the security guide.
Respond quickly: Return 200 as soon as you receive the webhook; process asynchronously if needed.

Next Steps

Entity Events

Handle entity lifecycle events

Transaction Events

Process transaction webhooks

Webhook Security

Secure your webhook endpoints

Configuration

Configure webhook settings

​Overview

​Why Use Risk Analysis Events?

Risk Score Sync

Workflow Automation

Audit Trail

Analytics & BI

​Available Events

​Event Payload Structure

​Key Payload Fields

​risk_analysis_entity_executed

​risk_analysis_transaction_executed

​Code Example

​Node.js – Handling Risk Analysis Events

​Best Practices

​Next Steps

Entity Events

Transaction Events

Webhook Security

Configuration

Overview

Why Use Risk Analysis Events?

Available Events

Event Payload Structure

Key Payload Fields

risk_analysis_entity_executed

risk_analysis_transaction_executed

Code Example

Node.js – Handling Risk Analysis Events

Best Practices

Next Steps