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

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:

Campos Principais do Payload

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

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