Saltar para o conteúdo principal
Os sinais de risco permitem que você alimente dados de detecção de fraude no Truthlocks de qualquer provedor upstream — serviços de impressão digital de dispositivos, APIs de reputação de IP, ferramentas de verificação de e-mail, mecanismos de análise de documentos ou suas próprias regras internas. Uma vez ingeridos, os sinais estão disponíveis através da API e da página Risco e Fraude > Sinais no console.
O Firewall de Identidade Antifraude está geralmente disponível. Todos os cinco caminhos de detecção — ingestão direta de sinal, normalização de eventos, varredura de deepfake, detecção de ATO e pontuação de velocidade — são integrados com exemplos de API multilíngues (cURL, JavaScript, Python), guias completos e notificações de webhook em tempo real para todos os tipos de sinal. Decisões de risco automatizadas, gerenciamento de casos e exportação SIEM de fraude já estão disponíveis.
Você pode criar sinais de cinco maneiras:
  • Ingestão direta — envie um sinal totalmente pontuado via POST /v1/risk/signals quando você já tiver uma pontuação de risco de um provedor externo. Suporta novas tentativas idempotentes via o cabeçalho Idempotency-Key.
  • Normalização de eventos — envie um evento de identidade bruto via POST /v1/risk/events e deixe a plataforma mapeá-lo para um tipo de sinal e pontuação base automaticamente. Consulte normalização de eventos.
  • Pontuação de sinal de deepfake e falsificação de identidade — envie indicadores ou pontuações produzidos externamente para avaliação de limite via POST /v1/risk/deepfake/scan. Scans que pontuam 60 ou mais automaticamente ingerem um sinal de risco. Consulte o guia de detecção de deepfake.
  • Detecção de tomada de conta — avalie eventos de login contra heurísticas baseadas em velocidade via POST /v1/risk/ato/evaluate. Alertas são criados e sinais de risco são ingeridos automaticamente quando os limites são excedidos. Consulte o guia de detecção de ATO.
  • Pontuação de velocidade e anomalia — registre as ações do sujeito via POST /v1/risk/velocity/record e faça com que a plataforma rastreie a frequência em janelas de tempo contínuas (1 m, 5 m, 1 h, 24 h). Ações que produzem uma pontuação de velocidade ponderada de 60 ou superior ingerem automaticamente um sinal de risco. Consulte o guia de pontuação de velocidade.

Escolhendo um caminho de ingestão

Todos os cinco caminhos produzem os mesmos registros de sinal de risco. Você pode consultar, filtrar e revisar sinais de qualquer caminho usando o endpoint de lista e a página do console Risco e Fraude > Sinais.

Como funciona

1

Sinais de ingestão

Envie uma solicitação POST para /v1/risk/signals com a fonte do sinal, tipo, pontuação de risco e o assunto a que se refere. Anexe qualquer contexto extra no objeto payload.
2

Consultar e filtrar

Use GET /v1/risk/signals para listar sinais com filtros para origem, tipo de sinal, assunto e pontuação mínima. Os resultados são paginados com paginação baseada em cursor.
3

Revisar no console

Abra Risco e Fraude > Sinais na console do locatário para navegar pelos sinais, filtrar por fonte ou pontuação e inspecionar detalhes de sinais individuais.

Pré-requisitos

  • Um inquilino Truthlocks ativo com uma chave de API
  • Pelo menos uma fonte upstream de detecção de fraude que produz sinais pontuados

Ingestão de um sinal

Envie uma requisição POST com os campos obrigatórios:

Campos obrigatórios

Campos opcionais

Idempotência

Inclua um cabeçalho Idempotency-Key (UUID) para evitar sinais duplicados durante as retentativas. Se você enviar a mesma chave duas vezes, a duplicata será ignorada silenciosamente.

Consultando sinais

Listar com filtros

Filtros disponíveis:

Obter um único sinal

Visualização do Console

A página Risco e Fraude > Sinais no console fornece uma lista pesquisável e filtrável de todos os sinais ingeridos. Cada linha mostra a origem, tipo, pontuação (codificada por cores por gravidade), referência do assunto e carimbo de data/hora. Use os filtros na parte superior da página para restringir os resultados por fonte, tipo de sinal ou pontuação mínima. Clique em qualquer linha para ver os detalhes completos do sinal, incluindo o objeto de metadados payload.

Diretrizes de pontuação

A pontuação consistente entre as fontes torna a análise downstream mais confiável. Recomendamos os seguintes intervalos:
Pontuações iguais ou superiores a 80 acionam decisões de revisão automática. A interpretação da pontuação além do limite automático é por sua conta — a plataforma armazena e retorna as pontuações como estão e não as normaliza entre as fontes.

Normalização de eventos

Em vez de construir sinais de risco manualmente, você pode enviar eventos de identidade brutos e deixar a plataforma normalizá-los em sinais automaticamente. Isso é útil quando você deseja alimentar eventos nativos da plataforma — logins falhos, assinaturas inválidas, suspeitos de deepfake — diretamente no pipeline de risco sem mapeá-los para tipos de sinal você mesmo. Envie uma requisição POST para /v1/risk/events com a origem, tipo e assunto do evento:
A resposta inclui tanto o event_id bruto quanto o signal_id normalizado, para que você possa rastrear todo o pipeline do evento ao sinal:
Quando normalized é true, o evento correspondeu a um mapeamento conhecido. Quando false, a plataforma usou o fallback genérico.

Mapeamentos de eventos integrados

A plataforma vem com mapeamentos pré-calibrados para eventos de identidade comuns: Tipos de evento desconhecidos são aceitos com o tipo de sinal behavior e uma pontuação base de 10.

Campos de evento

Obrigatório: Opcional:
Use a normalização de eventos quando seus eventos se originarem de dentro da plataforma (logins, verificações, atestações). Use o endpoint de ingestão direta de sinal quando você já tiver um sinal pontuado de uma fonte externa.

Isolamento de inquilino

Os sinais de risco são totalmente isolados por inquilino usando segurança em nível de linha (RLS). Cada sinal é vinculado ao inquilino autenticado no momento da ingestão, e as consultas só podem retornar sinais que pertencem ao inquilino chamador.

Detecção de deepfake e personificação

A API de detecção de deepfake estende o pipeline de sinal de risco com varredura automatizada para conteúdo manipulado e fraude de identidade. Envie imagens, vídeos, documentos ou atestados para análise, e as varreduras que excedem o limite de risco criam automaticamente um sinal de risco — nenhuma chamada de API extra é necessária. Consulte o guia de detecção de deepfake e personificação para o fluxo de trabalho completo, referência de indicadores e exemplos de código.

Detecção de aquisição de conta

A API de detecção de ATO estende o pipeline de sinal de risco com monitoramento de login baseado em velocidade. Envie eventos de login para POST /v1/risk/ato/evaluate e a plataforma rastreia tentativas falhas por assunto em uma janela contínua de uma hora. Quando um assunto ultrapassa um limite (5, 10 ou 20 logins falhos), um alerta é criado e um sinal de risco é ingerido automaticamente — nenhuma chamada de API extra é necessária. Consulte o guia de detecção de aquisição de conta para o fluxo de trabalho completo, referência de limite e padrões de integração.

Pontuação de velocidade e anomalia

A API de pontuação de velocidade estende o pipeline de sinal de risco com rastreamento de ações em várias janelas e detecção de anomalias. Registre qualquer ação do sujeito via POST /v1/risk/velocity/record e a plataforma rastreia a frequência em quatro janelas contínuas (1 m, 5 m, 1 h, 24 h). Uma pontuação de velocidade ponderada é calculada a partir das contagens da janela, com viés para janelas curtas para detecção de rajadas. Quando a pontuação atinge 60 ou mais, um sinal de risco com signal_type: "velocity" é ingerido automaticamente — nenhuma chamada de API extra é necessária. Consulte o guia de pontuação de velocidade e anomalia para o fluxo de trabalho completo, modelo de pontuação e padrões de integração.

Notificações de webhook

Sinais de risco criados por qualquer um dos cinco caminhos de detecção podem acionar notificações webhook em tempo real. Assine risk.signal.created ou risk.signal.escalated para reagir a novos sinais sem sondagem. Isso cobre sinais de ingestão direta, normalização de eventos, varreduras de deepfake, alertas de ATO e anomalias de velocidade. Consulte o guia de webhooks para exemplos de payload e padrões de integração.

Medição de uso

Os recursos Anti-Fraude são medidos por ciclo de faturação. Cada caminho de deteção incrementa o seu próprio contador de uso: As cotas variam de acordo com o nível do plano. Você pode verificar seu consumo atual com a API de uso ou no console em Configurações > Faturamento > Uso na seção Anti-Fraude. Para verificar se uma operação específica é permitida antes de realizá-la, use o endpoint de verificação de limite.
A resposta inclui todos os contadores Anti-Fraude com os campos used, limit e period para que você possa monitorar o consumo programaticamente.
Consulte a visão geral de faturamento para a lista completa de 16 produtos medidos e suas taxas padrão.

O que vem a seguir