Os seus dados, onde você toma a decisão
Cada identificação pode chegar aos seus sistemas de duas formas: enviada ao seu servidor no instante em que acontece, ou puxada por você no segundo exato em que decide. Os dois canais carregam os mesmos números — e essa parte é travada por um teste, não por uma promessa.
Push ou pull
Os webhooks empurram eventos para você conforme eles acontecem. A Data API permite que você pergunte no momento em que precisa de uma resposta. A maioria dos times usa os dois: webhooks para registrar e reagir, a Data API para checar em linha.
Webhooks — push, em tempo real
Fazemos POST de um evento JSON assinado no seu endpoint no instante em que algo acontece: um visitante é identificado, um roubo de conta é sinalizado, um ataque de bots começa. Nada para ficar consultando, nada para agendar.
Melhor para: registrar cada visita, reagir a ataques, alimentar o seu data warehouse ou SIEM.
Latência de entrega p50 de 44–140 ms, do evento até o seu endpoint.
Data API — pull, sob demanda
Uma API privada de servidor para servidor. O seu backend se autentica com uma chave secreta e lê exatamente o que sabemos sobre um visitante no segundo em que decide — normalmente dentro de um handler de login ou de checkout.
Melhor para: uma checagem em linha antes de cobrar um cartão, aprovar um cadastro ou liberar uma conta.
Disponível a partir do plano Pro.
Quatro tipos de evento, um envelope
Toda entrega chega no mesmo envelope, com o tipo do evento no corpo e no cabeçalho X-Tracio-Event-Type — assim um único handler consegue rotear os quatro.
Visitante identificado
O evento central: uma visita foi pontuada. Carrega o ID de visitante, navegador e sistema operacional, geolocalização e rede, o veredito de bot e a decisão de risco. É entregue em fases — um evento primário no carregamento da página e depois uma fase tardia ou de correção quando evidências mais lentas mudam o veredito. Correlacione as fases pelo requestId.
identificationRoubo de conta
O detector de roubo de conta disparou em uma visita: o dispositivo por trás de uma conta conhecida não se parece mais com o dispositivo dono dela. Chega como evento próprio, com o contexto da conta anexado, em vez de se esconder dentro de um corpo de identificação.
account_takeoverAtaque de bots
Uma onda de tráfego automatizado no seu workspace. Este não tem visita por trás — é um alerta no nível do workspace, então os blocos de visita simplesmente não aparecem no corpo, em vez de chegarem como cascas vazias com pontuações zeradas.
attack_detectedMudança de reputação
Um perfil mudou de faixa de reputação. O mesmo envelope do alerta de ataque — um evento no nível do perfil, sem visita anexada, carregando a faixa nova e a anterior.
reputation_changedUma entrega, resumida
Este é o corpo base. O Pro adiciona a velocidade de visitas; o Business adiciona códigos de motivo do veredito, sinais de comportamento, orientações e dados de dispositivo entre navegadores a esta mesma forma — blocos novos aparecem, caminhos existentes nunca mudam de lugar.
{ "version": 2, "event": "identification", "eventId": "req_8f21c4:primary", "requestId": "req_8f21c4", "phase": "primary", "visitorId": "3f9a1b2c4d5e6f70", "timestamp": "2026-07-30T12:00:00Z", "geo": { "country": "DE", "city": "Berlin", "timezone": "Europe/Berlin" }, "network": { "vpn": true, "proxy": false, "tor": false, "datacenter": false }, "bot": { "result": "human", "score": 12 }, "identification": { "confidence": 0.97, "incognito": false }, "decision": { "action": "suspicious", "riskScore": 65.9 }}Toda requisição carrega duas assinaturas
X-Tracio-Signature é um HMAC-SHA256 sobre o timestamp da assinatura concatenado ao corpo bruto da requisição, com a chave do seu webhook — ele prova que quem enviou conhece o segredo que vocês dois têm. X-Tracio-Signature-Ed25519 é a assinatura da plataforma: você a verifica com uma chave pública buscada em um endpoint conhecido, então não há nada secreto para guardar do seu lado. O timestamp faz parte do conteúdo assinado, e é isso que torna inútil reproduzir uma captura antiga.
Verifique contra os bytes brutos da requisição: reserializar o JSON muda os bytes e a assinatura não vai bater. As retentativas carregam o mesmo X-Tracio-Event-Id, então deduplique por ele.
Cabeçalhos em toda entrega
X-Tracio-Signature: t=1753444800,v1=5257a869e7ecebed...X-Tracio-Signature-Ed25519: t=1753444800,kid=k1,v1=0Zx0M0n8...X-Tracio-Event-Type: identificationX-Tracio-Event-Id: req_8f21c4:primaryX-Tracio-Delivery-Attempt: 1X-Tracio-Payload-Version: 2Construído para não perder eventos
A entrega roda em uma frota dedicada, e a fonte da verdade é a fila, não a memória de um processo. É isso que torna o “pelo menos uma vez” real: se um nó de entrega morre no meio do voo, o evento continua na fila e outro nó o assume.
Retentativas do tamanho de quedas reais
5 s, 30 s, 2 min, 10 min, 30 min, 2 h, 6 h. As primeiras retentativas caem dentro de um minuto, então uma reinicialização rápida do seu serviço não custa nada. Cada pausa é sorteada entre metade do valor listado e o valor cheio, para que as retentativas não voltem como uma única rajada depois de uma queda.
Desativação automática que não dispara à toa
Um webhook só é desligado quando as falhas atingem o limiar e já duram pelo menos 15 minutos seguidos — uma rajada de entregas enfileiradas durante um restart não mata a integração. Um 410 Gone desativa na hora. O painel mostra o motivo, o código de resposta e um botão para reativar.
Rotação de segredo sem janela descoberta
Depois de uma rotação, os dois segredos continuam válidos por 24 horas e o cabeçalho carrega as duas assinaturas, então bater em qualquer uma já basta. Você atualiza a sua configuração dentro da janela em vez de correr atrás de um corte; “Revogar agora” encurta a janela quando você precisa que ela acabe.
Um log de entregas que dá para ler
Cada tentativa — código de resposta, duração, texto do erro — é visível por webhook no painel, ao lado de uma ação de teste que envia ao seu endpoint um payload de exemplo assinado, para você confirmar o seu verificador antes de ir para produção.
Pergunte no momento em que decide
Uma API privada de servidor para servidor em api.tracio.ai. O seu backend se autentica com uma chave secreta e lê os próprios dados. Ela deliberadamente não envia cabeçalhos CORS: uma chave secreta dá acesso a tudo no seu workspace e nunca pode chegar a um navegador. Disponível a partir do plano Pro.
| Método | Caminho | Retorna |
|---|---|---|
| GET | /v1/visitors/{visitorId} | Resumo do visitante: primeira e última vez visto, contagem de visitas, IPs e países únicos, navegadores e dispositivos, histórico de risco — mais a sessão mais recente dele. |
| GET | /v1/visitors/{visitorId}/sessions | Lista de sessões com paginação por cursor e filtros por intervalo de datas, resultado de bot e pontuação de risco mínima. |
| GET | /v1/visitors/{visitorId}/sessions/latest | A sessão mais recente como um objeto único, sem envelope de lista. |
| GET | /v1/sessions/{requestId} | Uma sessão específica. Passe o visitorId junto e a busca vai pelo índice de visitantes em vez de todo o seu histórico. |
| GET | /v1/visitors/{visitorId}/velocity | Atividade em uma janela — 1h, 24h ou 7d: quantas visitas, de quantos IPs, de quantos países, sob quantas contas. |
Checando um visitante no checkout
A chamada típica: dentro do seu handler de pagamento, antes de autorizar o cartão. Uma requisição, uma resposta, e o bloco meta informa a janela que você realmente obteve — se você pedir seis meses e o seu plano retiver 30 dias, ele devolve 30 dias e diz isso.
Requisição
# Inside your checkout handler, before you authorize the cardcurl -s -H "Authorization: Bearer $TRACIO_SECRET_KEY" \ "https://api.tracio.ai/v1/visitors/3f9a1b2c/velocity?window=24h"Resposta
{ "window": "24h", "events": 128, "uniqueIps": 4, "uniqueCountries": 2, "uniqueAccounts": 1, "meta": { "plan": "business", "retentionDays": 30 }}Os mesmos números em todo lugar
Uma visita que pontua 65,9 no seu painel pontua 65,9 na Data API e 65,9 no corpo do webhook. Duas renderizações independentes poderiam divergir — escalas são o jeito clássico, um canal te entregando 0,93 onde o outro diz 93 —, então um teste de paridade monta uma visita, renderiza por ambos os canais e compara os campos públicos no JSON bruto. A concordância é imposta, não apenas afirmada.
Conselho, não só números
As pontuações dizem o que vimos. As orientações dizem o que fazer a respeito, para as quatro decisões que realmente custam dinheiro — calculadas por regras versionadas, com o raciocínio anexado.
Aceitar o pagamento?
Pesa risco, reputação de fraude e o veredito de bot antes de você autorizar um cartão.
Aceitar o cadastro?
Pega a conta descartável antes de ela existir — multicontas e reputação pesam mais aqui.
Deixar entrar?
Aperta automaticamente quando o detector de roubo de conta disparou na visita.
Contar a conversão?
Separa uma indicação genuína de uma autoindicação ou de um bot incentivado.
Um vocabulário de quatro palavras
Cada cenário recebe uma de quatro respostas e, com ela, a base sobre a qual foi emitida — os eixos decisivos de um vocabulário fixo: bot, risco, reputação de fraude, comportamento, multicontas, roubo de conta, rede, padrão de afiliado. Você sempre sabe qual eixo moveu o conselho, sem nunca ver nomes de sinais, pesos ou limiares.
Um cálculo, três canais
O mesmo bloco de orientações viaja no webhook, responde na Data API e aparece no cartão do visitante no painel — um conjunto de regras, um resultado, nenhuma conciliação do seu lado. Leia o conselho do seu cenário em vez do geral: o geral é simplesmente o mais rígido dos quatro, um resumo para painéis e não uma decisão de pagamento. A versão das regras vai no payload, então uma mudança de regras é algo que você percebe, não algo que deduz de um conselho que mudou.
"guidance": { "version": 1, "overall": "review", "payment": "review", "registration": "challenge", "login": "allow", "affiliate": "allow", "basis": ["risk", "fraud_reputation"]}Cinco SDKs no front-end, dois canais no back-end
O lado do navegador é distribuído como cinco SDKs — JavaScript puro, React, Vue 3, Angular e Svelte 5. Não existem SDKs de servidor, e isso é deliberado: o seu backend se integra por HTTP simples, via webhooks assinados e a Data API. Verificar a assinatura são doze linhas contra um vetor de referência que publicamos, e não sobra nada extra para ficar atualizando na árvore de dependências do seu servidor.
Perguntas frequentes
Coloque no ar em uma tarde
Crie um webhook no painel, aponte para o seu endpoint e clique em Testar. Verifique a assinatura contra o nosso vetor de referência, e a parte difícil já ficou para trás.