Os webhooks entregam eventos de identificação ao seu servidor em tempo real. Toda vez
que um visitante é identificado, a TRACIO envia uma requisição HTTP POST para a URL
de webhook que você configurou. O corpo da requisição é o payload do evento.
Eles também são o único canal que entrega vereditos tardios — aqueles em que o comportamento de um visitante provou que ele era automatizado depois que a página já havia carregado.
Configure-os no painel, em Settings → Webhooks. Webhooks exigem o plano Pro ou superior.
| Evento | Quando | Plano |
|---|---|---|
identification | Em toda visita — as fases primary, late e correction | Todos |
account_takeover | O comportamento sob uma conta não corresponde mais ao perfil do titular | Business+ |
account_assessment | O estado da avaliação de roubo de conta de uma conta: avaliada e sem divergência, avaliada e divergente, ou não avaliada | Business+ |
attack_detected | Um pico de bots no seu site | Business+ |
reputation_changed | A reputação de uma pessoa vinculada passou para outra faixa | Business+ |
transaction_state_changed | O desfecho de uma transação que você enviou para POST /v2/transactions mudou | Business+ |
login_risk | Uma avaliação de login por POST /v2/logins/assess terminou com challenge ou review | Todos |
trusted_device_enrolled | Um dispositivo passou a ser confiável para uma conta, ou a confiança nele foi renovada | Todos |
trusted_device_revoked | A confiança em um dispositivo foi revogada — pela API ou pelo painel | Todos |
affiliate_threshold_crossed | A recomendação para um afiliado piorou (none → review, none → hold, review → hold) | Todos |
Os nomes dos eventos usam sublinhados, nunca pontos — não existe visitor.created nem
session.created.
Um webhook assina tipos específicos; o valor separado * significa "todo tipo,
incluindo os adicionados depois". Cinco tipos são a exceção: * não inclui
account_assessment, login_risk, trusted_device_enrolled,
trusted_device_revoked e affiliate_threshold_crossed — informe cada um deles
explicitamente. account_assessment reporta cobertura, e não uma descoberta, por
isso chega aproximadamente uma vez por visita que traz um linked_id — uma ordem de
volume diferente da dos outros eventos. Os tipos de risco de login e de afiliados só
fazem sentido para uma integração que chama essas APIs. Um curinga que você configurou
antes de esses eventos existirem não é consentimento para recebê-los.
Um tipo desconhecido é rejeitado com 400 quando uma assinatura é criada ou editada,
de modo que um erro de digitação não deixe você com um webhook que silenciosamente
nunca dispara.
identificationUma única visita produz até três entregas que compartilham o mesmo request_id:
primary — o veredito inicial, no carregamento da página.late — enriquecimento cerca de nove segundos depois, quando as verificações lentas chegam.correction — uma correção baseada no comportamento (ponteiro, teclado, rolagem).Correlacione-as pelo request_id e diferencie-as pelo phase. A fase posterior tem
precedência: se primary disse human e correction diz bot, a segunda é a
resposta correta.
Não confie na ordem de chegada. Cada fase é entregue de forma independente e com
seu próprio cronograma de retry — se primary entrou em retry enquanto late teve
sucesso na primeira tentativa, você as receberá em ordem inversa. Determine a
precedência pelo campo phase, não pelo horário de recebimento.
Essas três são as únicas fases de um evento identification. Um outro valor chega até
você: account_takeover e account_assessment carregam phase: "beacon", porque
ambos são levantados a partir do beacon comportamental da sessão.
Repare no descompasso que isso cria, porque ele afeta a idempotência. Uma entrega de
identification em produção tem event_id exatamente igual a <request_id>:<phase>,
mas outras entregas quebram essa fórmula. Um account_takeover é <request_id>:ato —
o sufixo é o literal ato, e não o valor do campo phase — e um account_assessment
é <request_id>:ato-state-<state>. Uma entrega de teste enviada pelo painel é
<request_id>:test, enquanto o phase no corpo ainda diz primary — e um corpo em
esquema 1 não tem campo phase nenhum, de modo que o cabeçalho é o único lugar onde
esse sufixo aparece. Use o event_id diretamente como chave de idempotência e nunca o
remonte a partir de request_id e phase. Case pelos valores que você trata e ignore
o resto, em vez de rejeitar a entrega.
Alguns eventos não têm visita: attack_detected (nível de workspace),
reputation_changed (nível de pessoa), transaction_state_changed (nível de
transação), login_risk, trusted_device_enrolled e trusted_device_revoked (nível
de conta) e affiliate_threshold_crossed (nível de afiliado). Eles não têm
request_id, nem visitor_id, nem nenhum dos blocos browser, geo, bot ou
decision — essas chaves simplesmente não existem, assim como o cabeçalho
X-Tracio-Request-Id. Já account_takeover e account_assessment são produzidos por
uma visita específica e carregam o corpo de identificação completo do seu plano. Se
você processa todos os eventos em um único handler, verifique event antes de tocar
em campos de visita.
Webhooks novos usam a versão 3 do payload. Webhooks existentes na versão 1 ou 2 mantêm a versão que selecionaram; os dois esquemas antigos estão congelados e serão removidos em 2027-04-12. Para migrar, selecione a versão 3 no cartão do webhook, no painel.
| Versão | Status |
|---|---|
1 | Congelada; removida em 2027-04-12 |
2 | Congelada; removida em 2027-04-12 |
3 | O padrão para webhooks novos; chaves em snake_case |
A versão 3 traz os mesmos campos e valores da versão 2, com chaves em snake_case e um
version: 3 no nível superior. O algoritmo de assinatura e os cabeçalhos não mudam
(X-Tracio-Payload-Version: 3). As chaves dentro do seu próprio dicionário fields
são dados seus e não são renomeadas.
| v2 | v3 |
|---|---|
eventId | event_id |
requestId | request_id |
visitorId | visitor_id |
linkedId | linked_id |
userAgent | user_agent |
network.connectionType | network.connection_type |
network.proxyDetected | network.proxy_detected |
network.realIp | network.real_ip |
bot.antidetectScore | bot.antidetect_score |
identification.matchType | identification.match_type |
identification.matchConfidence | identification.match_confidence |
identification.incognitoVisits | identification.incognito_visits |
identification.driftScore | identification.drift_score |
decision.riskScore | decision.risk_score |
decision.suspectScore | decision.suspect_score |
deviceInfo | device_info |
deviceInfo.deviceId | device_info.device_id |
deviceInfo.crossBrowser | device_info.cross_browser |
deviceInfo.linkedBrowsers | device_info.linked_browsers |
screen.colorDepth | screen.color_depth |
screen.pixelRatio | screen.pixel_ratio |
clientHints | client_hints |
clientHints.platformVersion | client_hints.platform_version |
clientHints.deviceName | client_hints.device_name |
osEnvironment | os_environment |
environment.virtualMachine | environment.virtual_machine |
spoofing.spoofedAxes | spoofing.spoofed_axes |
spoofing.anonymousBrowser | spoofing.anonymous_browser |
session.durationSeconds | session.duration_seconds |
velocity.uniqueIps | velocity.unique_ips |
velocity.uniqueLocations | velocity.unique_locations |
accountAlert | account_alert |
accountAlert.accountId | account_alert.account_id |
accountAlert.driftScore | account_alert.drift_score |
accountAssessment | account_assessment |
accountAssessment.accountId | account_assessment.account_id |
accountAssessment.profile.windowsEffective | account_assessment.profile.windows_effective |
accountAssessment.profile.oldestWindowAgeSeconds | account_assessment.profile.oldest_window_age_seconds |
attack.windowMinutes | attack.window_minutes |
attack.recentBots | attack.recent_bots |
attack.recentTotal | attack.recent_total |
personId | person_id |
reputation.overallRisk | reputation.overall_risk |
linkedAccountsCount | linked_accounts_count |
linkedVisitorsCount | linked_visitors_count |
reputationChange | reputation_change |
reputationChange.personId | reputation_change.person_id |
reputationChange.previousBand | reputation_change.previous_band |
reputationChange.visitorIds | reputation_change.visitor_ids |
reputationChange.linkedAccountsCount | reputation_change.linked_accounts_count |
{ "version": 3, "event": "identification", "event_id": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31:primary", // "<request_id>:<phase>" — the idempotency key "request_id": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31", // visit identifier, shared by all phases "phase": "primary", "visitor_id": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y", "linked_id": "user-42", // your ?lid=, if you passed one "tag": "checkout", "fields": { "order_ref": "A-1029", "plan": "pro" }, // custom fields that arrived with the visit "timestamp": "2026-07-30T12:00:00Z", "url": "https://shop.example.com/checkout", "ip": "203.0.113.44", "user_agent": "Mozilla/5.0 …", "browser": { "name": "Chrome", "version": "138" }, "os": { "name": "macOS", "version": "15.5" }, "device": "desktop", "gpu": "Intel Iris Plus Graphics 655", // modelo do adaptador de vídeo, normalizado; ausente quando desconhecido "geo": { "country": "DE", "city": "Berlin", "lat": 52.52, "lon": 13.405, "timezone": "Europe/Berlin" }, "network": { "vpn": false, "proxy": true, "tor": false, "datacenter": true, "connection_type": "DCH", "proxy_detected": true // o tráfego HTTP e o caminho de rede bruto saem por redes diferentes }, "bot": { "result": "human", "score": 3.2 }, // human | bot | uncertain "identification": { "confidence": 0.97, "incognito": false }, "decision": { "action": "real", "risk_score": 12.2 }, // real | fake | suspicious "extensions": ["metamask", "privacy_badger"] // detected browser extensions; absent when none}Valores zero e vazios são omitidos. Campos de string e numéricos com valor zero
(bot.type para um humano, ou bot.antidetect_score: 0, por exemplo) estão ausentes
do JSON — não os torne obrigatórios nos seus esquemas e leia os blocos aninhados de
forma defensiva.
bot.score e decision.risk_score são decimais em escala 0..100 com uma casa
após a vírgula — exatamente os números que o painel e a Data API reportam para a mesma
visita. (No esquema congelado da v1 eles usam unidades diferentes: uma fração 0..1 e
0..255, respectivamente.)
bot.type é o nome de um bot reconhecido, um agente de IA verificado
(ai_agent:<vendor>) ou um rótulo de família. Veja
Tipos de bot para o vocabulário — nomes internos de
verificações nunca são expostos, em nenhum plano. ai_agent:<vendor> significa que a
requisição provou ter vindo da infraestrutura desse fornecedor — uma assinatura Web
Bot Auth válida feita com uma chave que o fornecedor publica, ou um endereço dentro
das faixas de IP que o fornecedor publica — em vez de apenas alegar isso no user
agent. Uma requisição que alega ser um agente de IA e é contrariada por todas as
provas que o fornecedor publica é reportada como impersonation.
| Campo | Tipo | Descrição |
|---|---|---|
version | number | Versão do esquema do payload (3) |
event | string | Tipo do evento |
event_id | string | Identificador da entrega — a chave de idempotência; único por evento e compartilhado por todos os seus webhooks que o recebem, estável entre retries |
request_id | string | Identificador da visita (UUID), compartilhado por todas as fases dela |
phase | string | primary, late, correction; account_takeover e account_assessment trazem beacon |
visitor_id | string | Identificador de visitante estável |
linked_id | string | Identificador vinculado fornecido pelo cliente |
tag | string | Tag personalizada fornecida pelo cliente |
fields | object | Campos personalizados anexados à visita no momento da coleta. Apenas o que chegou com a visita — um campo anexado depois pela Data API nunca aparece em um webhook, em nenhuma fase ou retry. Chaves e valores são strings. Ausente quando a visita não trouxe campos |
timestamp | string | Horário do evento (RFC 3339) |
url | string | URL da página onde o evento foi capturado |
ip | string | Endereço IP do cliente |
user_agent | string | String de user-agent bruta do cliente |
browser.name / .version | string | Navegador detectado |
os.name / .version | string | Sistema operacional detectado |
device | string | Classe do dispositivo (p. ex. desktop, mobile) |
gpu | string | Modelo do adaptador de vídeo conforme informado pelo navegador (WebGL), normalizado para um nome legível (Intel Iris Xe Graphics, Apple M1 Pro); Software renderer para rasterizadores por software; ausente quando desconhecido |
geo | object | Geolocalização por IP: country, city, lat, lon, timezone |
network | object | vpn, proxy, tor, datacenter (booleanos) e connection_type |
network.proxy_detected | boolean | O tráfego HTTP da visita e seus caminhos de rede brutos saem por redes diferentes — um proxy ou VPN à frente do navegador. Dois endereços do mesmo provedor (NAT da operadora, uma segunda saída da mesma VPN) não contam |
bot.result | string | human, bot ou uncertain |
bot.type | string | Nome do bot, agente de IA verificado ou rótulo de família quando um bot é detectado |
bot.score | number | Pontuação de bot (0–100) |
identification.confidence | number | Confiança da identificação (0.0–1.0) |
identification.incognito | boolean | Contexto de navegação privada/anônima |
decision.action | string | real, fake ou suspicious |
decision.risk_score | number | Pontuação de risco agregada (0–100) |
extensions | array | Extensões de navegador detectadas nesta visita, como slugs de máquina estáveis (nomes, categorias e links das lojas estão no painel e na Data API). Ausente quando nada foi detectado |
Pro e acima — como o visitante se comporta ao longo do tempo:
{ "identification": { "match_type": "exact", // exact | fuzzy | new — how the visitor was recognized "match_confidence": 0.93, "visits": 42, "incognito_visits": 3 }, // Present when visitor counters are available at event time (usually primary). // A missing block means "no data", not "zeros". "velocity": { "events5m": 7, "unique_ips": 2, "unique_locations": 1 }, "bot": { "antidetect_score": 0 }, // antidetect indicators, 0..100 "session": { "duration_seconds": 95 } // the correction phase and the account_takeover alert}Business e acima — por que o veredito saiu do jeito que saiu:
{ "reasons": [ // at most 8, sorted by importance { "code": "headless_browser", "severity": "high" }, { "code": "privacy_hardening", "severity": "low" } ], // Behavioral biometrics — present only when behavioral scoring ran for the // visit. A missing block means "no data", never "nothing suspicious". "behavior": { "score": 87, "verdict": "human", "confidence": 0.92 }, // The smoothed behavior score the account-takeover verdict was made on. It is // measured by beacons that arrive after the identification event, so it is // empty in identification deliveries — see the account_takeover event. "identification": { "drift_score": 0.41 }, "device_info": { "device_id": "…", // the physical device across browsers on it "cross_browser": true, "confidence": 0.88, "linked_browsers": 3 }, "network": { "isp": "Deutsche Telekom", "asn": 3320, // o endereço público observado no caminho de rede bruto, ou seja, o // endereço atrás do proxy ou da VPN; ausente quando nenhum endereço desse // tipo foi observado "real_ip": { "address": "203.0.113.7", "country": "NL", "isp": "KPN" } }, "geo": { "isp": "Deutsche Telekom" }, // O ambiente de desktop MEDIDO em uma máquina Linux ("Mint 22+", "Ubuntu", // "GNOME", "KDE"); um User-Agent não consegue expressar uma distribuição. // Ausente quando não determinado — na maioria das visitas Linux e em todas // as que não são Linux. "os_environment": "Mint 22+", // O que a visita afirmou sobre si mesma em comparação com o que // verificações independentes mediram. Presente apenas quando uma // falsificação foi de fato detectada; um campo `real` vazio significa "a // verificação permaneceu em silêncio", nunca "confirmado". No eixo `gpu`, // `claimed.gpu` carrega o adaptador declarado com o mesmo nome de modelo // legível do campo `gpu` de nível superior. "spoofing": { "detected": true, "claimed": { "os": "Windows 10", "browser": "Chrome 139.0" }, "real": { "os": "macOS" }, "spoofed_axes": ["os", "screen"], // os | gpu | screen | network | browser "anonymous_browser": { "detected": true, "names": ["Linken Sphere"] } }, // Fatos do dispositivo — o que o navegador do visitante informa sobre a // máquina, higienizado do nosso lado. screen: resolução, profundidade de // cor e device pixel ratio. locale: os idiomas preferidos e o fuso horário // do próprio navegador — ao contrário de geo.timezone, que é derivado do // endereço IP; uma divergência entre os dois é um sinal comum de // localização falsificada. client_hints: User-Agent Client Hints — // arquitetura e bitness da CPU, modelo do dispositivo (Android: o código // do modelo em `model`, p. ex. "SM-A556B", e seu nome comercial da lista // de dispositivos do Google Play em `device_name`, p. ex. // "Samsung Galaxy A55 5G") e a versão exata da plataforma; apenas // navegadores baseados em Chromium os informam. Cada bloco fica ausente // quando a visita não trouxe esses dados, então trate cada um como // opcional. "screen": { "width": 2560, "height": 1600, "color_depth": 30, "pixel_ratio": 2 }, "locale": { "languages": ["en-US", "de"], "timezone": "Europe/Berlin" }, "client_hints": { "architecture": "arm", "bitness": "64", "platform_version": "15.5.0" }, // Presente apenas quando o adaptador de vídeo se identificou como virtual; // hypervisor é um dicionário fechado (vmware, virtualbox, parallels, qemu, // hyperv, bochs, intel-gvt, vgpu). Um bloco ausente significa que não há // tal indício. "environment": { "virtual_machine": true, "hypervisor": "vmware" }, "decision": { "suspect_score": 4.1 }, "guidance": { "version": 3, "overall": "review" } // see below}Veja Detecção de bots para o vocabulário dos
códigos de motivo e o que severity significa.
Campos de multicontas (Business e acima). Quando o modo de pessoa está habilitado
para o seu workspace, o corpo também traz person_id, um bloco reputation (score,
categories, overall_risk), linked_accounts_count e linked_visitors_count — se o
visitante está vinculado a outros visitantes e contas. A camada de pessoa atualmente
funciona em modo de observação e, até entrar em produção, esses campos ficam ausentes
do corpo. Não os torne obrigatórios nos seus esquemas.
guidance carrega recomendações prontas de "o que fazer" por ponto de integração,
para que você não precise derivar uma política a partir de pontuações brutas. Ele está
presente em todo evento v3 Business+ — allow é declarado explicitamente:
{ "guidance": { "version": 3, "overall": "review", // the strictest advice across the scenarios "payment": "review", // whether to accept the payment "registration": "challenge", // whether to create the account "login": "challenge", // whether to let them into the account "affiliate": "review", // whether to credit the conversion to the partner "basis": ["risk", "network"] // the axes that determined the advice }}Todo cenário começa em allow e só se move para cima na escada:
allow → challenge → review → deny. Dentro de um cenário vence o eixo mais
rigoroso que disparar, e overall é o mais rigoroso entre os quatro cenários.
| Recomendação | Pagamento | Cadastro | Login | Afiliado |
|---|---|---|---|---|
allow | Processe | Crie | Deixe entrar | Credite a conversão |
challenge | 3-D Secure / confirmação | Captcha, confirmação por e-mail ou telefone | 2FA reforçado, reautenticação | Marque como duvidosa até haver atividade |
review | Processe, mas coloque na fila de revisão | Crie com restrições | Deixe entrar e gere um alerta | Segure o repasse até a revisão |
deny | Não processe a transação | Recuse a criação da conta | Não deixe entrar | Não credite a conversão |
basis lista os eixos que determinaram a recomendação — um eixo cuja proposta foi
mais branda do que a adotada não entra na lista. Leia-o pelo código, em vez de supor
um conjunto fixo:
Eixo (basis) | O que significa |
|---|---|
list | O visitante correspondeu a uma das listas do seu workspace em modo enforce. Uma lista allow sobrepõe todos os eixos: todo cenário vira allow e basis é exatamente ["list"] |
rule | A visita correspondeu a uma das regras do seu workspace em modo enforce; uma regra move apenas a recomendação do seu próprio cenário (uma regra allow suaviza só aquele) e é ignorada quando uma lista já agiu |
bot | O detector de bots concluiu que se trata de automação — nega todos os cenários |
risk | A decisão e a pontuação de risco geral da visita |
behavior | A biometria comportamental diz bot com confiança suficiente — acrescenta fricção em vez de recusa |
account_takeover | O comportamento sob esta conta não corresponde mais ao perfil do titular — login para challenge, pagamento para review |
network | Tor, ou uma VPN saindo de um datacenter |
affiliate_pattern | O formato de indicações autogeradas — a conversão de afiliado é retida como challenge |
fraud_reputation, multiaccounting | A reputação e o agrupamento de contas da pessoa por trás do visitante; aparecem quando a camada de pessoa entrar em produção |
version é a versão do conjunto de regras — ela é incrementada conforme a lógica
melhora, então mantenha-a nos seus logs. A versão 2 introduziu o eixo list, o
primeiro capaz de suavizar uma recomendação; a versão 3 levou os limiares de login de
account_takeover para a escala da pontuação do veredito de roubo de conta, de modo
que a mesma visita pode receber deny onde a versão 2 dava challenge, e vice-versa.
Guidance é aditivo: novos cenários chegam como novas chaves sem quebrar o contrato. A
fase posterior vence, exceto no caso de recomendações parciais: uma entrega
calculada sobre um conjunto incompleto de entradas é marcada com "partial": true, e
uma recomendação parcial não sobrepõe uma recomendação completa recebida antes
para o mesmo request_id. Em uma entrega comum, o campo partial está totalmente
ausente.
Os limiares exatos deliberadamente não são documentados. Uma recomendação que pode ser
submetida a engenharia reversa até virar uma pontuação deixa de ser uma defesa. Há
exatamente uma exceção deliberada: account_assessment.verdict.threshold, a fronteira
de decisão do veredito de roubo de conta descrita abaixo.
account_takeoverApenas Business e Enterprise; nos planos inferiores nenhuma entrega é criada, mesmo
que um webhook assine este evento. O corpo é o envelope de identificação completo do
seu plano mais um bloco account_alert e o bloco account_assessment descrito na
próxima seção, entregue no máximo uma vez por visita:
{ "version": 3, "event": "account_takeover", "event_id": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31:ato", "request_id": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31", "phase": "beacon", // o alerta é levantado a partir de um beacon; só o event_id diz "ato" "account_alert": { "type": "behavior-drift/2", // kind of alert and the version of its construction "account_id": "user-42", // your linked_id for the account "drift_score": 0.71 // the value the verdict was made on }, "account_assessment": { "type": "behavior-drift/2", "account_id": "user-42", "state": "assessed_alert", "verdict": { "severity": "high", "score": 0.71, "threshold": 0.3565, "scale": "manhattan-normalized", "basis": "ring", "windows": 9 }, "profile": { "windows": 6, "windows_effective": 5, "oldest_window_age_seconds": 1837 } } // …the remaining identification fields}Por que type carrega uma versão. A construção por trás da pontuação já mudou
antes: a escala e a base do veredito. behavior-drift/2 é a primeira construção
versionada. Se você calibrou suas próprias regras sobre o número, trate uma mudança
desse valor como um sinal para revisá-las.
account_alert.drift_score e identification.drift_score são o mesmo número
(desde 2026-10-03): a pontuação de comportamento suavizada sobre a qual o veredito foi
tomado, medida contra o anel de janelas confiáveis passadas do titular da conta. Antes
dessa data, identification.drift_score trazia uma distância bruta em outra escala —
não misture valores de antes e depois dessa data. Quando uma janela não foi avaliada,
o campo fica ausente em vez de zero. Use account_assessment.verdict quando precisar
do número junto com o limiar com que ele foi comparado.
Na v1 o bloco é accountAlert com type, linkedId e drift, e não há bloco de
avaliação. Na v2 o alerta renomeia dois campos — linkedId → accountId e drift →
driftScore — e acrescenta accountAssessment; a v3 usa os nomes em snake_case acima.
Atualize seu handler quando trocar de versão, ou sua lógica de roubo de conta vai parar
silenciosamente de enxergar os dados.
account_assessmentApenas Business e Enterprise. Exige uma assinatura explícita: * não o inclui.
Sem este evento, a ausência de um alerta significa duas coisas diferentes ao mesmo tempo: ou avaliamos a sessão contra o perfil do titular da conta e ela correspondeu, ou não conseguimos avaliá-la — o perfil do titular não está pronto, a janela era esparsa demais ou o tráfego não era de uma pessoa. Ambos os casos parecem silêncio, e silêncio é lido como segurança. Geralmente não é: em um dia completo de produção em setembro de 2026, nos abstivemos de dar um veredito em 73% das janelas e 80% das contas. Um processo construído sobre "nenhum alerta significa que está bem" é construído sobre um estado que, na maior parte das vezes, não temos.
{ "version": 3, "event": "account_assessment", "event_id": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31:ato-state-not_assessed", "request_id": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31", "phase": "beacon", "account_assessment": { "type": "behavior-drift/2", "account_id": "user-42", "state": "not_assessed", // always present, one of three values "reason": "profile_not_ready", // only when state is not_assessed "profile": { "windows": 3, // windows in the owner's reference ring "windows_effective": 2, // of those, how many yielded a distance "oldest_window_age_seconds": 1837 } } // …the remaining identification fields}state nunca está ausente e nunca está vazio:
state | Significado | O que fazer |
|---|---|---|
assessed_clear | Avaliada; o comportamento corresponde ao do titular | Nada |
assessed_alert | Avaliada; o comportamento diverge | Step-up — o alerta account_takeover traz o mesmo veredito |
not_assessed | Nenhum veredito foi emitido | Não trate como limpa; recorra aos seus próprios sinais |
reason (apenas com not_assessed):
reason | Significado |
|---|---|
profile_not_ready | A referência do titular atualmente não consegue produzir um veredito para esta conta. Trate isso como um estado, não como uma etapa: ele pode nunca mudar, então não espere |
profile_learning | A referência ainda está sendo acumulada |
window_too_sparse | Havia uma pessoa, mas a janela trouxe interação de menos |
not_computable | A janela e a referência não tinham eixos informativos em comum |
bot_traffic | Havia dados suficientes, e não havia uma pessoa a avaliar |
Desde 2026-10-04 18:00 UTC, window_too_sparse e not_computable não são mais
emitidos para um titular cuja referência está pronta — uma janela assim é reportada
como profile_not_ready. Os dois motivos continuam na lista porque entregas
anteriores os trazem: se o seu handler se ramifica por eles, encaminhe
profile_not_ready da mesma forma e não compare as taxas desses motivos entre antes e
depois dessa data.
state e reason não dependem do plano. verdict é Business+, assim como
drift_score.
O bloco verdict está presente apenas com assessed_clear e assessed_alert.
Com not_assessed o bloco fica ausente em vez de preenchido com zeros — um score de
0 ao lado de um threshold de 0 seria lido como "o comportamento correspondeu
exatamente".
| Campo | Significado |
|---|---|
severity | low ou high — duas faixas, deliberadamente: uma faixa intermediária exigiria um segundo limiar na mesma escala |
score | O valor sobre o qual o veredito foi tomado |
threshold | O valor com o qual ele foi de fato comparado |
scale | Como a pontuação é construída: manhattan-normalized é d/(1+d) em um espaço comportamental normalizado, onde 0 significa correspondência exata |
basis | ring — distância até a mais próxima das janelas confiáveis passadas do titular; centroid — distância até o perfil médio dele |
windows | Quantas janelas foram agregadas na pontuação |
score e threshold estão sempre na mesma escala, nomeada, de modo que o par
reproduz a decisão: o alerta dispara exatamente quando score > threshold.
Com que frequência chega. No máximo uma entrega por estado por visita — na
prática, uma por visita que traz um linked_id, e não uma por janela comportamental.
Um estado pode mudar dentro de uma visita — por exemplo, a referência termina de
aprender e not_assessed vira assessed_clear — e então você recebe as duas, em
ordem. Essa transição é possível, não prometida: profile_not_ready pode persistir
por toda a vida da conta.
O que ele não promete. As contas mais bem protegidas são as de usuários ativos com sessões longas e um perfil de referência completo; as menos protegidas são as de usuários pouco frequentes, para quem um roubo de conta é mais perigoso. Isso é uma propriedade da construção, não um limiar que possa ser ajustado. O evento reporta uma divergência comportamental em relação a uma referência — não é uma promessa de detectar roubo de conta em geral.
attack_detectedO alerta de pico de bots chega no envelope comum da v3 com um bloco attack. Ele não
tem campos de identificação — é um evento em nível de workspace:
{ "version": 3, "event": "attack_detected", "event_id": "c0a8e1f2-…", // alert id; matches X-Tracio-Event-Id "timestamp": "2026-07-30T12:00:00Z", "attack": { "kind": "bot_spike", "severity": "critical", // warning | critical "window_minutes": 15, "recent_bots": 4210, "recent_total": 5100, "expected": 180.5 // the baseline expected over a window this size }}Webhooks na versão 1 do payload recebem o esquema histórico plano de alerta — ele não muda.
login_risk, trusted_device_enrolled e trusted_device_revokedEsses três eventos vêm das suas próprias chamadas à API de risco de login
(POST /v2/logins/assess) e aos dispositivos confiáveis dela. Eles são entregues
apenas com uma assinatura explícita pelo nome — * não os inclui — e apenas para
webhooks na versão 2 ou 3 do payload; a versão 1 não tem corpo para eles.
login_risk é enviado quando uma avaliação retorna challenge ou review — nunca
em allow, deny ou not_assessed. O bloco login_risk dele é a avaliação
armazenada, exatamente como a resposta síncrona a devolveu. ID do evento:
login-risk:<id>, onde <id> é o nosso identificador do registro armazenado — pegue
o seu próprio assessment_id do corpo.trusted_device_enrolled e trusted_device_revoked são enviados a cada cadastro,
renovação e revogação de um dispositivo confiável. O bloco trusted_device deles —
user_id, device_ref, enrolled_at, expires_at, revoked_at, revoked_by
(api ou dashboard) — é um retrato no momento do evento; com
trusted_device_enrolled, revoked_at e revoked_by são null. ID do evento:
trusted-device:<n>.Eles são enviados de forma assíncrona, até cerca de cinco segundos após a chamada, e
não trazem o cabeçalho X-Tracio-Request-Id — use login_risk.request_id para
encontrar a visita. O webhook é uma notificação para auditoria e alertas; a decisão em
si é a resposta síncrona.
{ "version": 3, "event": "login_risk", "event_id": "login-risk:4b1f9e2c-6d3a-4f80-9b7e-2a5c8d1e0f37", "timestamp": "2026-10-17T10:00:00Z", "login_risk": { "assessment_id": "snap-1", "user_id": "alice", "state": "assessed", "recommendation": "challenge", "reasons": ["new_device"] // …the rest of the assessment }}{ "version": 3, "event": "trusted_device_revoked", "event_id": "trusted-device:7", "timestamp": "2026-10-17T11:00:00Z", "trusted_device": { "user_id": "alice", "device_ref": "7978151c54e94838", "enrolled_at": "2026-10-17T10:00:00Z", "expires_at": "2026-11-16T10:00:00Z", "revoked_at": "2026-10-17T11:00:00Z", "revoked_by": "dashboard" }}affiliate_threshold_crossedEntregue apenas com uma assinatura explícita pelo nome — * não o inclui — e
apenas para webhooks na versão 2 ou 3 do payload. A cada 15 minutos a TRACIO recalcula
a pontuação de qualidade de cada afiliado com dados suficientes e envia o evento
quando a recomendação dele piora: none → review, none → hold ou review → hold.
Uma melhora não envia nada e permite que a próxima piora seja reportada de novo. O
evento pertence ao workspace: ele vai para os webhooks assinantes de todos os
ambientes e não traz o cabeçalho X-Tracio-Request-Id. ID do evento:
affiliate-threshold:<affiliate_id>:<recommendation>:<unix time>.
{ "version": 3, "event": "affiliate_threshold_crossed", "event_id": "affiliate-threshold:aff_17:review:1792490400", "timestamp": "2026-10-20T10:00:00Z", "affiliate_threshold": { "affiliate_id": "aff_17", "recommendation": "review", // none | review | hold "previous_recommendation": "none", "quality_score": 72, // 0..100, higher is better "hold_days": 14, // the current hold period of the workspace "crossed_at": "2026-10-20T10:00:00Z", "metrics": { "reg_to_ftd": 0.31, "active14_share": 0.42, "dup_device_share": 0.3, "dup_person_share": 0.1, "ring_share": 0.05, "bonus_hunter_share": 0.2, "dc_vpn_bot_share": 0.1, "chargeback_share": 0.03, "affiliate_fraud_share": 0, "no_visit_share": 0.05 } }}metrics são as proporções do afiliado nos últimos 90 dias, as mesmas que o relatório
do painel mostra: a proporção de cadastros que chegaram a um primeiro depósito
(reg_to_ftd), a proporção de jogadores ainda ativos 14 dias após o cadastro
(active14_share) e as proporções de conversões com dispositivo ou pessoa duplicados,
de um anel de fraude, de caçadores de bônus, de um datacenter, VPN ou bot, marcadas
como chargeback ou como fraude de afiliado, e sem visita encontrada. A TRACIO apenas
recomenda — a retenção em si e qualquer decisão de pagamento ficam na sua plataforma de
afiliados. Na versão 2 do payload o mesmo corpo tem chaves em camelCase: o bloco é
affiliateThreshold, com affiliateId, previousRecommendation, qualityScore e
assim por diante.
transaction_state_changedBusiness e acima. Enviado quando o desfecho de uma transação que você enviou para
POST /v2/transactions muda: as regras decidiram REVIEW ou DECLINE (um APPROVE
não envia nada), um analista enviou a transação para revisão no painel, ou um rótulo
foi definido, substituído ou removido. Use-o para segurar um bônus enquanto uma
solicitação está em revisão e para retê-lo ou liberá-lo quando o desfecho estiver
definido, sem polling. * inclui este evento; ele é entregue apenas para webhooks na
versão 2 ou 3 do payload. Um webhook vinculado a um ambiente o recebe apenas para esse
ambiente.
{ "version": 3, "event": "transaction_state_changed", "event_id": "txn-state:7d1c2b3a-0000-4000-8000-000000000042:118", "timestamp": "2026-10-15T10:04:00Z", "transaction": { "id": "7d1c2b3a-0000-4000-8000-000000000042", "transaction_id": "bonus-claim-1842", "state": "REVIEW", // always the decision of the rules "fraud_score": 50, "effective_state": "DECLINE", // the outcome to act on "recommendations": ["withhold_bonus"], "label": "fraud_detection_bonus_abuse", "label_source": "api", // api | dashboard "label_at": "2026-10-15T10:04:00Z", "previous_effective_state": "REVIEW" // …applied_rules and evidence, as in the transaction response }}| Chave | Significado |
|---|---|
effective_state | O desfecho com base no qual agir: o estado do analista ou do rótulo, quando houver um; caso contrário, state |
recommendations | O que fazer com o bônus, derivado de effective_state |
label, label_source, label_at | O rótulo atual, onde foi definido (api ou dashboard) e quando; os três são null quando a transação não tem rótulo |
previous_effective_state | effective_state antes desta mudança; null para o evento enviado na decisão automática |
O bloco mostra a transação como ela está quando o evento é enviado: se duas
mudanças acontecem em rápida sequência, os dois eventos trazem o estado mais recente,
cada um com seu próprio previous_effective_state e timestamp. A ordem não é
garantida — ordene por timestamp e leia a transação pela API para obter o estado
atual. ID do evento: txn-state:<id>:created para a decisão automática e
txn-state:<id>:<n> para cada mudança posterior. O evento não diz quem definiu um
rótulo — apenas de onde ele veio.
reputation_changedBusiness e acima. Enviado quando a reputação entre clientes de uma pessoa que a sua
organização já viu passa para outra faixa (clean → suspicious, por exemplo). Exige
a camada de pessoa, que atualmente funciona em modo de observação — então o evento só
dispara para workspaces em que a resolução de identidade entre dispositivos está
habilitada. Este é um evento em nível de pessoa: ele não tem request_id nem blocos
de visita.
{ "version": 3, "event": "reputation_changed", "event_id": "person-reputation:pn_4f2a…:clean->suspicious:2026-07-30T12:10:00.123456Z", "timestamp": "2026-07-30T12:10:00Z", "reputation_change": { "person_id": "pn_4f2a…", "score": 46, "band": "suspicious", // clean | suspicious | fake "previous_band": "clean", "categories": ["chargeback"], "visitor_ids": ["X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y"], // the person's visitors in YOUR data "linked_accounts_count": 4 // omitted when zero }}A chave do bloco é reputation_change, e não reputation: esta última é usada pela
reputação no contexto de uma visita específica, e as duas são coisas diferentes. O
esquema 1 entrega a forma histórica plana — os mesmos campos no nível superior.
Toda entrega inclui um cabeçalho X-Tracio-Signature:
X-Tracio-Signature: t=1710432000,v1=5257a869e7ecebed…t é o timestamp Unix (em segundos) de quando a requisição foi assinada.v1 é o HMAC-SHA256 codificado em hexadecimal de "<t>.<rawRequestBody>", com o
seu segredo de webhook como chave.O timestamp faz parte do conteúdo assinado, o que dá proteção contra replay.
Duas coisas para acertar, ou a verificação falha em produção:
v1=. Durante uma rotação de
segredo o cabeçalho carrega duas assinaturas, e um parser que mantenha apenas
uma delas vai rejeitar entregas válidas durante toda a janela de rotação.// Express.js exampleimport express from "express"import crypto from "crypto"
const app = express()
// Capture the raw body so the signature can be verified byte-for-byte.app.use( express.json({ verify: (req, _res, buf) => { ;(req as any).rawBody = buf }, }),)
function verifySignature(rawBody: Buffer, header: string, secret: string): boolean { if (!header) return false
const parts = header.split(",").map((p) => p.trim()) const ts = parts.find((p) => p.startsWith("t="))?.slice(2) if (!ts) return false
// Replay protection: reject timestamps more than five minutes old. if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false
// Sign the raw bytes: the "<t>." prefix plus the raw request body. const signed = Buffer.concat([Buffer.from(`${ts}.`, "utf8"), rawBody]) const expected = crypto.createHmac("sha256", secret).update(signed).digest("hex") const exp = Buffer.from(expected, "hex")
// During a rotation window the header carries several v1= — any may match. return parts.some((p) => { if (!p.startsWith("v1=")) return false const got = Buffer.from(p.slice(3), "hex") // Compare lengths BEFORE timingSafeEqual: it throws on differing lengths, // and one junk header would turn the handler into a 500. return got.length === exp.length && crypto.timingSafeEqual(got, exp) })}
app.post("/webhook/tracio", (req, res) => { const header = req.headers["x-tracio-signature"] as string if (!verifySignature((req as any).rawBody, header, WEBHOOK_SECRET)) { return res.status(401).json({ error: "Invalid signature" }) }
const event = req.body console.log(`Visitor: ${event.visitor_id}`) console.log(`Bot: ${event.bot?.result}`) // "human" | "bot" | "uncertain"
res.status(200).send("OK")})Entregas com esquema 2 e 3 carregam adicionalmente X-Tracio-Signature-Ed25519
(t=<unix>,kid=<id>,v1=<base64>). Ambos os lados conhecem o segredo HMAC, então o
HMAC prova que quem enviou conhece o segredo, mas não que a requisição se originou na
TRACIO; a assinatura assimétrica prova. As chaves públicas são publicadas em
https://api.tracio.ai/.well-known/webhook-keys, indexadas por kid: leia o campo
public_key. O alias legado publicKey traz o mesmo valor e será removido em
2027-04-12.
Entregas de teste enviadas pelo painel são assinadas apenas com HMAC — a chave privada
da plataforma fica nos nós de entrega e deliberadamente não está disponível para o
painel. Um verificador que exija Ed25519 de forma rígida precisa deixar as entregas
de teste passarem (elas trazem o sufixo :test no event_id); caso contrário, os
testes pelo painel falham enquanto a produção está saudável. O mesmo cuidado vale para
checagens de formato: uma entrega de teste traz request_id no formato test_<hex> e
o literal test_visitor como visitor_id, de modo que um handler que valide esses
valores contra os formatos de produção vai rejeitar uma entrega que, no resto, está bem
formada.
Após uma rotação, ambos os segredos permanecem válidos por 24 horas e o cabeçalho carrega as duas assinaturas, então você pode atualizar sua configuração sem perder entregas. A ação Revoke now encurta a janela. Atualize o segredo do seu lado dentro de 24 horas: assim que a janela fecha, o segredo antigo para de corresponder, e se o seu endpoint responder a uma assinatura inválida com 4xx, cinco respostas assim seguidas desativam o webhook.
| Cabeçalho | Descrição |
|---|---|
Content-Type | application/json |
X-Tracio-Signature | t=<unix>,v1=<hmac_sha256_hex> — dois v1= durante uma janela de rotação |
X-Tracio-Signature-Ed25519 | Assinatura de plataforma, t=<unix>,kid=<id>,v1=<base64> (somente v2 e v3) |
X-Tracio-Event-Id | Identificador da entrega — a chave de idempotência |
X-Tracio-Request-Id | Identificador da visita, corresponde a request_id (somente v2 e v3). Enviado apenas para eventos de visita — identification, account_takeover e account_assessment |
X-Tracio-Event-Type | O tipo do evento (somente v2 e v3) |
X-Tracio-Delivery-Attempt | Número da tentativa, começando em 1 (somente v2 e v3) |
X-Tracio-Payload-Version | 3 ou 2 (somente v2 e v3) |
X-Tracio-Webhook-Id | Identificador do webhook que produziu esta entrega |
Entregas podem ser repetidas, e um retry carrega o mesmo X-Tracio-Event-Id.
Deduplique por ele:
app.post("/webhook/tracio", async (req, res) => { const eventId = req.headers["x-tracio-event-id"] as string
const existing = await db.webhooks.findOne({ eventId }) if (existing) return res.status(200).send("Already processed")
await db.webhooks.insert({ eventId, processedAt: new Date() }) await processWebhookEvent(req.body)
res.status(200).send("OK")})Note que event_id é único por evento, não por webhook: se vários webhooks do
workspace assinam o mesmo evento, cada um recebe uma entrega com o mesmo
identificador. Para identification ele é montado como <request_id>:<phase>, e é
por isso que as três fases de uma mesma visita são deduplicadas de forma independente,
em vez de colapsarem em uma só. Eventos sem visita têm suas próprias formas — veja
cada evento acima.
Responda com 2xx — é o único sinal de que uma entrega foi aceita.
| Resposta | O que acontece |
|---|---|
2xx | Entrega concluída |
429 Too Many Requests | Não conta como falha e não gasta uma tentativa; um Retry-After mais longo é respeitado |
408, 425, 5xx, conexão perdida | Repetido com uma pausa crescente |
410 Gone | O endpoint é tratado como removido — o webhook é desativado imediatamente |
Outros 4xx | Repetido, mas cinco seguidos desativam o webhook — 400/401/404 não se curam com retry |
Cronograma de retries: 5s → 30s → 2min → 10min → 30min → 2h → 6h (8 tentativas). Os primeiros retries cabem dentro de um minuto, então um reinício breve do seu serviço não lhe custa uma notificação. Cada pausa é randomizada entre metade e o valor completo, para que os retries não disparem todos de uma vez após uma indisponibilidade.
A desativação automática exige tanto um limiar (20 falhas consecutivas, ou 5 erros de configuração) quanto pelo menos 15 minutos consecutivos de falhas — um reinício breve não consegue matar a integração, mesmo que muitas entregas estivessem enfileiradas. Um intervalo maior que 15 minutos reinicia a contagem. O painel mostra o motivo, com o código de resposta e o texto do erro, e um botão Re-enable que zera os contadores.
| Plano | Webhooks por workspace |
|---|---|
| Free | Não disponível |
| Pro | 5 |
| Business | 20 |
| Enterprise | 100 |
Os endpoints precisam ser https com IP público — endereços privados e de loopback
são rejeitados, inclusive em um redirecionamento — e não podem ter mais de dois
redirecionamentos de profundidade.
Apenas redirecionamentos 307 e 308 são seguidos. 301, 302 e 303 mandam o
cliente mudar para GET e descartar o corpo, então uma entrega não os segue e a
tentativa conta como falha. Se o seu balanceador de carga normaliza a URL (adicionando
www ou uma barra final), aponte o webhook direto para a URL final.
Os webhooks são gerenciados no painel. O painel aciona uma API de gerenciamento com
escopo de workspace, servida no host da aplicação (por exemplo
https://app.tracio.ai/api/v1), e os endpoints abaixo são exatamente os que ele chama.
Todo endpoint de webhook fica sob /workspaces/{wsId}.
Esta não é uma superfície servidor-a-servidor. A API de gerenciamento aceita apenas o JWT da sua sessão do painel, verificado contra o seu papel no workspace (RBAC); uma chave secreta
tracio_sk_…é rejeitada aqui. Como essa sessão vive no navegador e expira junto com ele, trate as chamadas abaixo como uma descrição do que o painel faz, e não como uma integração a ser automatizada. Para acesso programático a partir do seu próprio backend, use a Data API, que é somente leitura.
curl -X POST https://app.tracio.ai/api/v1/workspaces/{wsId}/webhooks \ -H "Authorization: Bearer <session-jwt>" \ -H "Content-Type: application/json" \ -d '{ "url": "https://your-server.com/webhook/tracio", "events": [] }'O segredo de assinatura é gerado pela TRACIO e retornado uma única vez na criação
(e na rotação) sob signingSecret. Guarde-o com segurança — é a chave que você usa
para verificar assinaturas.
{ "ok": true, "data": { "id": "b3d4f8a1-2c67-4e9b-8f05-7a1d3c9e2b48", "workspaceEnvironmentId": "b201f2ba-…", "url": "https://your-server.com/webhook/tracio", "events": [], "signingSecret": "f3a9…<hex>", "status": "active", "successRate": 100, "createdAt": "2026-07-30T12:00:00Z" }}Em leituras posteriores o signingSecret vem mascarado (null) — ele só é revelado
pela criação e pela rotação do segredo.
| Método | Caminho | Descrição |
|---|---|---|
GET | /workspaces/{wsId}/webhooks | Listar webhooks |
PATCH | /workspaces/{wsId}/webhooks/{webhookId} | Atualizar url / events / status |
DELETE | /workspaces/{wsId}/webhooks/{webhookId} | Excluir um webhook |
POST | /workspaces/{wsId}/webhooks/{webhookId}/test | Enviar uma entrega de teste assinada |
POST | /workspaces/{wsId}/webhooks/{webhookId}/secret/rotate | Rotacionar o segredo de assinatura |
GET | /workspaces/{wsId}/webhooks/{webhookId}/deliveries | Listar as tentativas de entrega recentes |
Retorne um 2xx o mais rápido possível e processe o payload de forma assíncrona para
evitar timeouts:
app.post("/webhook/tracio", async (req, res) => { res.status(200).send("OK") processWebhookEvent(req.body).catch(console.error)})
async function processWebhookEvent(event: WebhookPayload) { await db.events.insert(event)
if (event.decision?.risk_score > 50) { await alertFraudTeam(event) }
if (event.bot?.result === "bot") { await blockVisitor(event.visitor_id) }}Use a ação Test em um webhook (ou POST .../webhooks/{webhookId}/test) para
enviar um payload de exemplo assinado ao seu endpoint e confirmar que ele está
acessível e verificando assinaturas corretamente.
Para desenvolvimento local, exponha seu servidor com um túnel como o ngrok:
ngrok http 3000# Use the generated URL as your webhook endpoint