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

> Receba notificações em tempo real quando regras de conformidade são acionadas — com eventos webhook gu1 para integração downstream em tempo real.

## Visão Geral

Os eventos de webhook de regras permitem que você receba notificações em tempo real quando regras de conformidade ou negócio são acionadas para entidades na plataforma Gu1. Esses eventos permitem que você automatize ações de conformidade, alerte sua equipe e mantenha trilhas de auditoria quando condições de risco são detectadas.

## Por Que Usar Eventos de Regras?

<CardGroup cols={2}>
  <Card title="Conformidade em Tempo Real" icon="gavel">
    Receba alertas instantâneos quando regras de risco são acionadas
  </Card>

  <Card title="Ações Automatizadas" icon="robot">
    Bloqueie, sinalize ou escale entidades automaticamente
  </Card>

  <Card title="Trilha de Auditoria" icon="clipboard-list">
    Rastreie todos os acionamentos de regras para relatórios de conformidade
  </Card>

  <Card title="Gestão de Riscos" icon="shield-halved">
    Responda a condições de alto risco imediatamente
  </Card>
</CardGroup>

## Eventos Disponíveis

### rule.triggered

O evento `rule.triggered` é disparado quando uma regra de conformidade ou negócio é avaliada como verdadeira para uma entidade.

**Quando dispara**:

* Uma condição de regra é atendida durante criação ou atualização de entidade
* Avaliação periódica de regras detecta uma correspondência
* Regras de monitoramento de transações identificam atividade suspeita
* Verificações de conformidade (PEP, sanções, mídia adversa) retornam correspondências positivas

**Filtros disponíveis**:

* `ruleIds`: Receber apenas eventos para regras específicas
* `ruleSeverity`: Filtrar por nível de severidade (low, medium, high, critical)
* `entityTypes`: Filtrar por tipo de entidade

## Payload do Evento

### Payload de rule.triggered

```json theme={null}
{
  "event": "rule.triggered",
  "timestamp": "2025-01-07T14:00:00.000Z",
  "payload": {
    "ruleId": "550e8400-e29b-41d4-a716-446655440000",
    "rule": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "High Risk Country Check",
      "description": "Flags entities from high-risk countries",
      "severity": "high",
      "category": "geographic_risk",
      "isActive": true
    },
    "entityId": "123e4567-e89b-12d3-a456-426614174000",
    "entity": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "externalId": "customer_xyz789",
      "name": "John Doe",
      "type": "person",
      "countryCode": "KP",
      "status": "blocked"
    },
    "evaluationId": "eval_abc123",
    "triggerData": {
      "countryCode": "KP",
      "riskLevel": "critical",
      "matchedCriteria": [
        "sanctioned_country",
        "high_risk_jurisdiction"
      ],
      "additionalInfo": {
        "sanctionList": ["OFAC", "UN"],
        "riskScore": 95
      }
    },
    "action": {
      "type": "block",
      "reason": "Entity from sanctioned country",
      "automaticAction": true,
      "previousStatus": "under_review",
      "newStatus": "blocked"
    },
    "triggeredAt": "2025-01-07T14:00:00.000Z"
  }
}
```

### Campos Chave do Payload

<ResponseField name="ruleId" type="string">
  Identificador único da regra acionada
</ResponseField>

<ResponseField name="rule" type="object">
  Informações completas da regra incluindo nome, descrição, severidade e categoria
</ResponseField>

<ResponseField name="rule.severity" type="string">
  Nível de severidade: `low`, `medium`, `high`, ou `critical`
</ResponseField>

<ResponseField name="entityId" type="string">
  A entidade que acionou a regra
</ResponseField>

<ResponseField name="entity" type="object">
  Informações completas da entidade incluindo seu `externalId`
</ResponseField>

<ResponseField name="evaluationId" type="string">
  Identificador único para esta avaliação de regra
</ResponseField>

<ResponseField name="triggerData" type="object">
  Dados que causaram o acionamento da regra, incluindo critérios correspondentes e pontuações de risco
</ResponseField>

<ResponseField name="action" type="object">
  Ação tomada como resultado do acionamento da regra (opcional)
</ResponseField>

<ResponseField name="action.type" type="string">
  Tipo de ação: `block`, `flag`, `review`, `alert`, ou `none`
</ResponseField>

<ResponseField name="action.automaticAction" type="boolean">
  Se a ação foi tomada automaticamente pelo Gu1
</ResponseField>

## Categorias de Regras e Exemplos

### Regras de Risco Geográfico

Acionadas quando entidades são de países ou jurisdições de alto risco:

```json theme={null}
{
  "rule": {
    "name": "Sanctioned Country Check",
    "category": "geographic_risk",
    "severity": "critical"
  },
  "triggerData": {
    "countryCode": "IR",
    "sanctionList": ["OFAC", "EU"],
    "riskLevel": "critical"
  },
  "action": {
    "type": "block",
    "automaticAction": true
  }
}
```

### Regras PEP (Pessoa Politicamente Exposta)

Acionadas quando a entidade corresponde a bancos de dados PEP:

```json theme={null}
{
  "rule": {
    "name": "PEP Screening",
    "category": "pep_check",
    "severity": "high"
  },
  "triggerData": {
    "pepStatus": "confirmed",
    "position": "Former Government Official",
    "country": "XX",
    "matchConfidence": 0.95,
    "source": "World-Check"
  },
  "action": {
    "type": "review",
    "automaticAction": true
  }
}
```

### Regras de Triagem de Sanções

Acionadas quando a entidade aparece em listas de sanções:

```json theme={null}
{
  "rule": {
    "name": "OFAC Sanctions Screening",
    "category": "sanctions",
    "severity": "critical"
  },
  "triggerData": {
    "matchType": "exact",
    "sanctionList": "OFAC SDN",
    "matchedName": "John Doe",
    "listingDate": "2020-01-15",
    "program": "Counter Terrorism"
  },
  "action": {
    "type": "block",
    "automaticAction": true
  }
}
```

## Configuração de Filtros

### Filtrar por ID de Regra

Receber apenas eventos para regras específicas:

```json theme={null}
{
  "eventTypes": ["rule.triggered"],
  "filters": {
    "ruleIds": [
      "rule_sanctions_ofac",
      "rule_high_risk_country"
    ]
  }
}
```

### Filtrar por Severidade

Receber apenas alertas de severidade alta e crítica:

```json theme={null}
{
  "eventTypes": ["rule.triggered"],
  "filters": {
    "ruleSeverity": ["high", "critical"]
  }
}
```

### Filtrar por Tipo de Entidade

Receber apenas regras acionadas para pessoas:

```json theme={null}
{
  "eventTypes": ["rule.triggered"],
  "filters": {
    "entityTypes": ["person"]
  }
}
```

## Exemplos de Código

### Node.js - Lidando com Eventos de Regras

```javascript theme={null}
const express = require('express');
const app = express();

app.use(express.json({
  verify: (req, res, buf) => {
    req.rawBody = buf.toString('utf8');
  }
}));

app.post('/webhooks/rules', async (req, res) => {
  try {
    // Verificar assinatura (veja guia de segurança)
    if (!verifySignature(req.rawBody, req.headers['x-webhook-signature'])) {
      return res.status(401).json({ error: 'Invalid signature' });
    }

    const { event, payload } = req.body;

    if (event === 'rule.triggered') {
      await handleRuleTriggered(payload);
    }

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

async function handleRuleTriggered(payload) {
  const { rule, entity, triggerData, action, evaluationId } = payload;

  console.log(`Rule triggered: ${rule.name} for ${entity.name}`);

  // Registrar acionamento de regra
  await db.ruleTriggers.create({
    data: {
      ruleId: rule.id,
      ruleName: rule.name,
      entityId: entity.id,
      externalId: entity.externalId,
      severity: rule.severity,
      triggerData,
      evaluationId,
      triggeredAt: new Date()
    }
  });

  // Lidar com base na severidade
  switch (rule.severity) {
    case 'critical':
      await handleCriticalRule(rule, entity, triggerData, action);
      break;

    case 'high':
      await handleHighSeverityRule(rule, entity, triggerData, action);
      break;

    case 'medium':
      await handleMediumSeverityRule(rule, entity, triggerData, action);
      break;

    case 'low':
      await handleLowSeverityRule(rule, entity, triggerData, action);
      break;
  }

  // Lidar com base no tipo de ação
  if (action) {
    switch (action.type) {
      case 'block':
        await handleBlockAction(entity, action);
        break;

      case 'review':
        await handleReviewAction(entity, rule, action);
        break;

      case 'flag':
        await handleFlagAction(entity, rule, action);
        break;

      case 'alert':
        await handleAlertAction(entity, rule, action);
        break;
    }
  }
}

async function handleCriticalRule(rule, entity, triggerData, action) {
  console.log(`🚨 CRITICAL: ${rule.name} triggered for ${entity.name}`);

  // Bloquear entidade imediatamente se ainda não estiver bloqueada
  if (entity.status !== 'blocked') {
    await blockEntity(entity.id, rule.name);
  }

  // Alertar equipe de conformidade imediatamente
  await slack.send({
    channel: '#compliance-critical',
    priority: 'critical',
    message: `🚨 CRITICAL RULE TRIGGERED`,
    fields: {
      'Rule': rule.name,
      'Entity': entity.name,
      'External ID': entity.externalId,
      'Severity': rule.severity,
      'Action Taken': action?.type || 'none',
      'Details': JSON.stringify(triggerData, null, 2)
    }
  });

  // Criar caso de alta prioridade
  await compliance.createCase({
    entityId: entity.id,
    ruleId: rule.id,
    priority: 'critical',
    type: 'rule_trigger',
    data: { rule, entity, triggerData, action },
    assignTo: 'compliance-lead'
  });
}

app.listen(3000);
```

### Python - Lidando com Eventos de Regras

```python theme={null}
from flask import Flask, request, jsonify
import logging

app = Flask(__name__)

@app.route('/webhooks/rules', methods=['POST'])
def rules_webhook():
    try:
        # Verificar assinatura (veja guia de segurança)
        signature = request.headers.get('X-Webhook-Signature')
        raw_body = request.get_data(as_text=True)

        if not verify_signature(raw_body, signature):
            return jsonify({'error': 'Invalid signature'}), 401

        # Analisar webhook
        payload = request.json
        event = payload['event']
        data = payload['payload']

        if event == 'rule.triggered':
            handle_rule_triggered(data)

        return jsonify({'success': True}), 200

    except Exception as e:
        logging.error(f'Webhook error: {e}')
        return jsonify({'error': str(e)}), 500

def handle_rule_triggered(data):
    rule = data['rule']
    entity = data['entity']
    trigger_data = data['triggerData']
    action = data.get('action')

    logging.info(f"Rule triggered: {rule['name']} for {entity['name']}")

    # Registrar acionamento
    db.rule_triggers.insert({
        'rule_id': rule['id'],
        'rule_name': rule['name'],
        'entity_id': entity['id'],
        'external_id': entity['externalId'],
        'severity': rule['severity'],
        'trigger_data': trigger_data,
        'evaluation_id': data['evaluationId']
    })

    # Lidar com base na severidade
    severity_handlers = {
        'critical': handle_critical_rule,
        'high': handle_high_severity_rule,
        'medium': handle_medium_severity_rule,
        'low': handle_low_severity_rule
    }

    handler = severity_handlers.get(rule['severity'])
    if handler:
        handler(rule, entity, trigger_data, action)

def handle_critical_rule(rule, entity, trigger_data, action):
    logging.critical(f"CRITICAL: {rule['name']} triggered for {entity['name']}")

    # Bloquear entidade
    if entity['status'] != 'blocked':
        block_entity(entity['id'], rule['name'])

    # Alertar equipe
    slack.send({
        'channel': '#compliance-critical',
        'message': f"🚨 CRITICAL RULE TRIGGERED: {rule['name']}",
        'fields': {
            'Entity': entity['name'],
            'External ID': entity['externalId'],
            'Severity': rule['severity']
        }
    })

if __name__ == '__main__':
    app.run(port=3000)
```

## Melhores Práticas

<AccordionGroup>
  <Accordion title="Armazene Acionamentos de Regras para Auditoria">
    Sempre registre acionamentos de regras para trilhas de auditoria de conformidade:

    ```javascript theme={null}
    await db.ruleTriggers.create({
      data: {
        ruleId: rule.id,
        entityId: entity.id,
        evaluationId: evaluationId,
        triggerData,
        triggeredAt: new Date(),
        webhook: req.body
      }
    });
    ```
  </Accordion>

  <Accordion title="Lide com Severidade Apropriadamente">
    Implemente diferentes fluxos de trabalho com base na severidade:

    * **Critical**: Bloqueio imediato + alertas urgentes
    * **High**: Sinalizar para revisão + notificar equipe de conformidade
    * **Medium**: Fila para revisão periódica
    * **Low**: Apenas registrar + relatórios agregados
  </Accordion>

  <Accordion title="Implemente Idempotência">
    Use ID de avaliação para prevenir processamento duplicado:

    ```javascript theme={null}
    const processed = await db.webhookLog.findUnique({
      where: { evaluationId: payload.evaluationId }
    });

    if (processed) {
      return; // Pular duplicado
    }
    ```
  </Accordion>
</AccordionGroup>

## Próximos Passos

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

  <Card title="Eventos KYC" icon="id-card" href="/pt/webhooks/events/kyc-events">
    Processar eventos de verificação KYC
  </Card>

  <Card title="Segurança de Webhooks" icon="shield" href="/pt/webhooks/security">
    Proteger seus endpoints de webhook
  </Card>

  <Card title="Configuração" icon="gear" href="/pt/webhooks/configuration">
    Configurar ajustes de webhook
  </Card>
</CardGroup>