> ## 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álise de Risco

> Receba notificações em tempo real quando uma análise de risco (execução da matriz de risco) for concluída — com eventos webhook gu1 para integração downstream.

## Visão Geral

Os eventos de webhook de análise de risco permitem que você receba notificações em tempo real quando uma matriz de risco é executada em uma entidade (pessoa ou empresa) ou em uma transação. Gu1 envia solicitações HTTP POST para seu endpoint de webhook configurado após cada conclusão de análise de risco, para que você possa sincronizar pontuações de risco com sistemas externos, alimentar ferramentas de BI ou acionar fluxos de trabalho.

## Por Que Usar Eventos de Análise de Risco?

<CardGroup cols={2}>
  <Card title="Sincronização de Risco" icon="chart-line">
    Mantenha sistemas externos atualizados com as pontuações de risco mais recentes
  </Card>

  <Card title="Automação de Workflows" icon="robot">
    Acione processos quando a análise for concluída (ex.: escalonamento, relatórios)
  </Card>

  <Card title="Rastreamento de Auditoria" icon="clipboard-list">
    Registre cada execução de matriz de risco para conformidade
  </Card>

  <Card title="Analytics e BI" icon="database">
    Alimente resultados de risco em dashboards e relatórios
  </Card>
</CardGroup>

## Eventos Disponíveis

| Tipo de Evento                       | Descrição                                      | Quando Acionado                                                                                                                                       |
| ------------------------------------ | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `risk_analysis_entity_executed`      | Matriz de risco executada em pessoa ou empresa | Quando uma matriz de risco é executada em uma **pessoa** ou **empresa** (execução manual ou automática: entity\_created, enrichment\_completed, etc.) |
| `risk_analysis_transaction_executed` | Matriz de risco executada em transação         | Quando uma matriz de risco é executada em uma **transação** (ex.: na criação/atualização com regras aplicadas)                                        |

**Local do acionamento**: `apps/api/src/services/rules-execution.service.ts` (após execução bem-sucedida do motor de regras).

## Estrutura do Payload do Evento

Todos os webhooks de análise de risco seguem esta estrutura:

```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": "Médio", "range": "30-80" } },
      "riskMatrixName": "Matriz de entidades padrão",
      "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 Principais do Payload

<ResponseField name="entity" type="object">
  A entidade analisada: `id`, `type` (person | company | transaction), `name`, `taxId`, `externalId`
</ResponseField>

<ResponseField name="rulesExecutionSummary" type="object">
  Resumo da execução de regras: `rulesHit`, `rulesNoHit`, `actionsExecuted` (opcional), `totalScore`, `scoreResult`, `riskMatrixName`, `executionTimeMs`, `trigger`, `matchedRulesCount`. Pode ser null. Estrutura completa e exemplo: [Resumo de Execução de Regras](/pt/api-reference/rules-execution-summary).
</ResponseField>

<ResponseField name="riskScore" type="number">
  Pontuação de risco final da execução da matriz de risco
</ResponseField>

<ResponseField name="totalRules" type="number">
  Número total de regras avaliadas
</ResponseField>

<ResponseField name="successfulRules" type="number">
  Número de regras executadas com sucesso
</ResponseField>

<ResponseField name="executionTimeMs" type="number">
  Tempo de execução da análise de risco em milissegundos
</ResponseField>

<ResponseField name="triggerEvent" type="string">
  O que acionou a análise (ex.: `entity_created`, `enrichment_completed`, `manual`)
</ResponseField>

<ResponseField name="riskMatrixName" type="string">
  Nome da matriz de risco executada, ou null
</ResponseField>

<ResponseField name="auditId" type="string">
  ID do registro de auditoria da análise de risco, ou null
</ResponseField>

## risk\_analysis\_entity\_executed

Enviado quando uma matriz de risco é executada em uma entidade do tipo **pessoa** ou **empresa**.

**Quando é acionado**:

* Análise de risco manual no dashboard
* Acionamento automático na criação de entidade (quando regras são aplicadas)
* Após conclusão de enriquecimento (quando configurado para executar regras)
* Outros acionamentos automáticos que executam o motor de regras em uma entidade

**Payload**: Mesma estrutura acima; `entity.type` é `person` ou `company`.

## risk\_analysis\_transaction\_executed

Enviado quando uma matriz de risco é executada em uma **transação**.

**Quando é acionado**:

* Transação criada ou atualizada com regras aplicadas
* Qualquer fluxo que execute o motor de regras em uma transação

**Payload**: Mesma estrutura; `entity.type` é `transaction`. Para transações, `entity.name` costuma ser o ID externo ou identificador da transação.

## Exemplo de Código

### Node.js – Tratando Eventos de Análise de Risco

```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: 'Assinatura 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('Erro no webhook:', error);
    res.status(500).json({ error: error.message });
  }
});

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

  // Sincronizar pontuação de risco no seu sistema
  await db.entities.update({
    where: { externalId: entity.externalId },
    data: {
      riskScore,
      riskMatrixName,
      lastRiskAnalysisAt: new Date(),
      lastTriggerEvent: triggerEvent,
    },
  });

  // Opcional: acionar fluxos para alto risco
  if (riskScore >= 75) {
    await compliance.queueReview(entity.id, riskScore, auditId);
  }
}
```

## Melhores Práticas

* **Idempotência**: Use `entity.id` + `auditId` (ou timestamp) para não processar a mesma análise duas vezes.
* **Verificar assinatura**: Sempre valide `X-Webhook-Signature` conforme a [guia de segurança](/pt/webhooks/security).
* **Responder rápido**: Retorne 200 assim que receber o webhook; processe de forma assíncrona se necessário.

## Próximos Passos

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

  <Card title="Eventos de Transações" icon="credit-card" href="/pt/webhooks/events/transaction-events">
    Processe webhooks de transações
  </Card>

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

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