Skip to main content

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

Sincronização de Risco

Mantenha sistemas externos atualizados com as pontuações de risco mais recentes

Automação de Workflows

Acione processos quando a análise for concluída (ex.: escalonamento, relatórios)

Rastreamento de Auditoria

Registre cada execução de matriz de risco para conformidade

Analytics e BI

Alimente resultados de risco em dashboards e relatórios

​
Eventos Disponíveis

Tipo de EventoDescriçãoQuando Acionado
risk_analysis_entity_executedMatriz de risco executada em pessoa ou empresaQuando uma matriz de risco é executada em uma pessoa ou empresa (execução manual ou automática: entity_created, enrichment_completed, etc.)
risk_analysis_transaction_executedMatriz de risco executada em transaçãoQuando 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: 
{
  "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

​
entity
object
A entidade analisada: id, type (person | company | transaction), name, taxId, externalId
​
rulesExecutionSummary
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.
​
riskScore
number
Pontuação de risco final da execução da matriz de risco
​
totalRules
number
Número total de regras avaliadas
​
successfulRules
number
Número de regras executadas com sucesso
​
executionTimeMs
number
Tempo de execução da análise de risco em milissegundos
​
triggerEvent
string
O que acionou a análise (ex.: entity_created, enrichment_completed, manual)
​
riskMatrixName
string
Nome da matriz de risco executada, ou null
​
auditId
string
ID do registro de auditoria da análise de risco, ou null

​
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

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.
  • Responder rápido: Retorne 200 assim que receber o webhook; processe de forma assíncrona se necessário.

​
Próximos Passos

Eventos de Entidades

Trate eventos do ciclo de vida de entidades

Eventos de Transações

Processe webhooks de transações

Segurança de Webhooks

Proteja seus endpoints de webhook

Configuração

Configure ajustes de webhook