Webhooks deliver identification events to your server in real time. Every time a
visitor is identified, TRACIO sends an HTTP POST request to your configured
webhook URL. The request body is the event payload.
They are also the only channel that delivers late verdicts — the ones where a visitor's behavior proved they were automated after the page had already loaded.
Set them up in the dashboard under Settings → Webhooks. Webhooks require the Pro plan or higher.
| Event | When | Plan |
|---|---|---|
identification | On every visit — the primary, late and correction phases | All |
account_takeover | Behavior under an account no longer matches the owner's profile | Business+ |
account_assessment | The account-takeover assessment state of an account: judged and clear, judged and diverging, or not judged | Business+ |
attack_detected | A spike of bots on your site | Business+ |
reputation_changed | The reputation of a linked person moved to another band | Business+ |
transaction_state_changed | The outcome of a transaction you sent to POST /v2/transactions changed | Business+ |
login_risk | An assessment by POST /v2/logins/assess ended with challenge or review; deny (including self_excluded) is never published, while review caused by a link to a self-excluded account (self_excluded_link) is — see Login Risk; a failed attempt whose every reason is a bot visit or a burst (neutral reasons aside) is not published | All |
trusted_device_enrolled | A device was made trusted for an account, or its trust was renewed | All |
trusted_device_revoked | The trust of a device was revoked — through the Data API, from the dashboard or by Tracio after a recovery outcome executed | All |
recovery_risk | An assessment by POST /v2/recoveries/assess ended with challenge, hold or review; allow and deny are never published, and neither is an assessment whose every reason is recovery velocity (neutral reasons aside) — see Password Recovery | All |
recovery_hold_released | An operator released a recovery hold in the dashboard — see Password Recovery | All |
account_compromise_suspected | An assessment by POST /v2/logins/assess carried an account_action for your identity provider — see Login Risk | Business+ |
credential_stuffing_campaign | A credential-stuffing campaign against your sign-in form started, continues or ended — see Login Risk | Business+ |
affiliate_threshold_crossed | The recommendation for an affiliate got worse (none → review, none → hold, review → hold) | All |
Event names use underscores, never dots — there is no visitor.created or
session.created.
A webhook subscribes to specific types; the separate value * means "every type,
including those added later." Nine types are the exception: * does not include
account_assessment, login_risk, trusted_device_enrolled,
trusted_device_revoked, affiliate_threshold_crossed,
account_compromise_suspected, credential_stuffing_campaign, recovery_risk and
recovery_hold_released, and you have to name each of them explicitly. The two
credential-stuffing types are subscription-only: a webhook with * never receives
them, and a wildcard you set before they existed is not consent to receiving them.
account_assessment reports coverage rather than a finding, so it arrives roughly
once per visit that carries a linked_id — a different order of volume from the
others. The three login-risk types are produced by your own calls to the
login risk API, and they only make sense to an integration that
uses it (so do account_compromise_suspected and credential_stuffing_campaign,
which come from the failed attempts you report to it); recovery_risk and
recovery_hold_released come from your calls to the
password recovery API; affiliate_threshold_crossed
likewise only makes sense to an integration that sends affiliate conversions. A
wildcard you set before these events existed is not consent to receiving them.
An unknown type is rejected with 400 when a subscription is created or edited, so
a typo can't leave you with a webhook that silently never fires.
identification eventA single visit produces up to three deliveries that share the same request_id:
primary — the initial verdict, at page load.late — enrichment roughly nine seconds later, once the slow checks have landed.correction — a correction based on behavior (pointer, keyboard, scrolling).Correlate them by request_id and tell them apart by phase. The later phase
takes precedence: if primary said human and correction says bot, the
second one is the right answer.
Do not rely on arrival order. Each phase is delivered independently and on its
own retry schedule — if primary went into retry while late succeeded on the
first attempt, you will receive them in reverse order. Determine precedence from
the phase field, not from the time of receipt.
Those three are the only phases of an identification event. One other value
reaches you: account_takeover and account_assessment carry phase: "beacon",
because both are raised from the session's behavioural beacon.
Note the mismatch this creates, because it affects idempotency. A production
identification delivery has an event_id of exactly <request_id>:<phase>, but
other deliveries break that formula. An account_takeover is <request_id>:ato —
the suffix is the literal ato, not the value of the phase field — and an
account_assessment is <request_id>:ato-state-<state>. A test delivery sent from
the dashboard is <request_id>:test, while the phase in its body still reads
primary — and a schema 1 body has no phase field at all, so the header is the
only place that suffix appears. Use event_id as the idempotency key directly and
never reassemble it from request_id and phase. Match on the values you handle
and ignore anything else rather than rejecting the delivery.
Events with no visit are account_compromise_suspected (account level),
credential_stuffing_campaign (environment level), attack_detected (workspace
level), reputation_changed (person level), transaction_state_changed
(transaction level), login_risk, trusted_device_enrolled,
trusted_device_revoked, recovery_risk, recovery_hold_released (account level)
and affiliate_threshold_crossed (affiliate level). They have no
request_id, no visitor_id and none of the browser, geo, bot or decision
blocks — those keys are simply absent, as is the X-Tracio-Request-Id header.
account_takeover and account_assessment, by contrast, are produced by a
specific visit and carry the full identification body for your plan. If you parse
every event in one handler, check event before touching visit fields.
New webhooks use payload version 3. Existing webhooks on version 1 or 2 keep the version they selected; both older schemas are frozen and will be removed on 2027-04-12. To migrate, select version 3 on the webhook card in the dashboard.
| Version | Status |
|---|---|
1 | Frozen; removed on 2027-04-12 |
2 | Frozen; removed on 2027-04-12 |
3 | The default for new webhooks; snake_case keys |
Version 3 carries the same fields and values as version 2, with snake_case keys and
a top-level version: 3. The signature algorithm and the headers are unchanged
(X-Tracio-Payload-Version: 3). Keys inside your own fields dictionary are your
data and are not renamed.
| 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", // video adapter model, normalized; absent when unknown "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 // HTTP traffic and the raw network path exit through different networks }, "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}Zero and empty values are omitted. String and numeric fields with a zero value
(bot.type for a human, or bot.antidetect_score: 0, for example) are absent from
the JSON — do not make them required in your schemas, and read nested blocks
defensively.
bot.score and decision.risk_score are decimals on a 0..100 scale with one
digit after the decimal point — exactly the numbers the dashboard and the Data API
report for the same visit. (In the frozen v1 schema they use different units: a
0..1 fraction and 0..255 respectively.)
bot.type is either the name of a recognized bot, a verified AI agent
(ai_agent:<vendor>) or a family label. See Bot Types
for the vocabulary — internal check names are never exposed, on any plan.
ai_agent:<vendor> means the request proved it came from that vendor's
infrastructure — a valid Web Bot Auth signature made with a key the vendor
publishes, or an address inside the IP ranges the vendor publishes — rather than
merely claiming it in the user agent. A request that claims to be an AI agent and is
contradicted by every proof the vendor publishes is reported as impersonation.
| Field | Type | Description |
|---|---|---|
version | number | Payload schema version (3) |
event | string | Event type |
event_id | string | Delivery identifier — the idempotency key; unique per event and shared by all your webhooks that receive it, stable across retries |
request_id | string | Visit identifier (UUID), shared by all phases of a visit |
phase | string | primary, late, correction; account_takeover and account_assessment carry beacon |
visitor_id | string | Stable visitor identifier |
linked_id | string | Linked identifier supplied by the client |
tag | string | Custom tag supplied by the client |
fields | object | Custom fields attached to the visit at collection time. Only what arrived with the visit — a field attached later through the Data API never appears in a webhook, on any phase or retry. Keys and values are strings. Absent when the visit carried no fields |
timestamp | string | Event time (RFC 3339) |
url | string | Page URL where the event was captured |
ip | string | Client IP address |
user_agent | string | Raw client user-agent string |
browser.name / .version | string | Detected browser |
os.name / .version | string | Detected operating system |
device | string | Device class (e.g. desktop, mobile) |
gpu | string | Video adapter model as reported by the browser (WebGL), normalized to a readable name (Intel Iris Xe Graphics, Apple M1 Pro); Software renderer for software rasterizers; absent when unknown |
geo | object | IP geolocation: country, city, lat, lon, timezone |
network | object | vpn, proxy, tor, datacenter (booleans) and connection_type |
network.proxy_detected | boolean | The visit's HTTP traffic and its raw network paths exit through different networks — a proxy or VPN in front of the browser. Two addresses of the same provider (carrier NAT, a second exit of the same VPN) do not count |
bot.result | string | human, bot or uncertain |
bot.type | string | Bot name, verified AI agent or family label when a bot is detected |
bot.score | number | Bot score (0–100) |
identification.confidence | number | Identification confidence (0.0–1.0) |
identification.incognito | boolean | Private/incognito browsing context |
decision.action | string | real, fake or suspicious |
decision.risk_score | number | Aggregate risk score (0–100) |
extensions | array | Browser extensions detected in this visit, as stable machine slugs (names, categories and store links are in the dashboard and the Data API). Absent when nothing was detected |
Pro and above — how the visitor behaves over time:
{ "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 and above — why the verdict came out the way it did:
{ "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, // the public address observed on the raw network path, i.e. the address // behind the proxy or VPN; absent when no such address was observed "real_ip": { "address": "203.0.113.7", "country": "NL", "isp": "KPN" } }, "geo": { "isp": "Deutsche Telekom" }, // The desktop environment MEASURED on a Linux machine ("Mint 22+", "Ubuntu", // "GNOME", "KDE"); a User-Agent cannot express a distribution. Absent when // not determined — most Linux visits, and every non-Linux one. "os_environment": "Mint 22+", // What the visit claimed about itself versus what independent checks // measured. Present only when a spoof was actually detected; an empty // `real` field means "the check stayed silent", never "confirmed". With the // `gpu` axis, `claimed.gpu` carries the claimed adapter as the same readable // model name as the top-level `gpu` field. "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"] } }, // Device facts — what the visitor's browser reports about the machine, // sanitized on our side. screen: resolution, color depth and the device // pixel ratio. locale: the browser's own preferred languages and timezone — // as opposed to geo.timezone, which is derived from the IP address; a // mismatch between the two is a common sign of a spoofed location. // client_hints: User-Agent Client Hints — CPU architecture and bitness, // device model (Android: the model code in `model`, e.g. "SM-A556B", and // its marketing name from the Google Play device list in `device_name`, // e.g. "Samsung Galaxy A55 5G") and the exact platform version; only // Chromium-based browsers report them. Every block is absent when the // visit carried no such data, so treat each as optional. "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" }, // Present only when the video adapter identified itself as a virtual one; // hypervisor is a closed dictionary (vmware, virtualbox, parallels, qemu, // hyperv, bochs, intel-gvt, vgpu). A missing block means no such evidence. "environment": { "virtual_machine": true, "hypervisor": "vmware" }, "decision": { "suspect_score": 4.1 }, "guidance": { "version": 3, "overall": "review" } // see below}See Bot Detection for the reason-code
vocabulary and what severity means.
Multi-accounting fields (Business and above). Once person mode is enabled for
your workspace, the body also carries person_id, a reputation block (score,
categories, overall_risk), linked_accounts_count and linked_visitors_count —
whether the visitor is linked to other visitors and accounts. The person layer
currently runs in observation mode, and until it goes live these fields are absent
from the body. Do not make them required in your schemas.
guidance carries ready-made "what to do" recommendations per integration point,
so you don't have to derive a policy from raw scores. It is present in every v3
Business+ event — allow is stated explicitly:
{ "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 }}Every scenario starts at allow and only ever moves up the ladder:
allow → challenge → review → deny. Within a scenario the strictest firing
axis wins, and overall is the strictest across all four scenarios.
| Advice | Payment | Registration | Login | Affiliate |
|---|---|---|---|---|
allow | Process it | Create it | Let them in | Credit the conversion |
challenge | 3-D Secure / confirmation | Captcha, email or phone confirmation | Step-up 2FA, re-authenticate | Mark as doubtful until activity shows |
review | Process, but queue for review | Create with restrictions | Let them in, raise an alert | Hold the payout until reviewed |
deny | Do not process the transaction | Refuse to create the account | Do not let them in | Do not credit the conversion |
basis lists the axes that determined the advice — an axis whose proposal was
milder than the one adopted does not make the list. Read it by code rather than
assuming a fixed set:
Axis (basis) | What it means |
|---|---|
list | The visitor matched one of your workspace lists in enforce mode. An allow list overrides every axis: every scenario becomes allow and basis is exactly ["list"] |
rule | The visit matched one of your workspace rules in enforce mode; a rule moves only the advice of its own scenario (an allow rule softens just that one), and is skipped when a list already acted |
bot | The bot detector concluded this is automation — denies every scenario |
risk | The decision and the overall risk score of the visit |
behavior | Behavioral biometrics say bot with enough confidence — adds friction rather than refusal |
account_takeover | Behavior under this account no longer matches its owner's profile — login to challenge, payment to review |
network | Tor, or a VPN coming out of a datacenter |
affiliate_pattern | The shape of self-generated referrals — the affiliate conversion is held as challenge |
fraud_reputation, multiaccounting | The reputation and account clustering of the person behind the visitor; appear once the person layer is live |
version is the version of the rule set — it is bumped as the logic improves, so
keep it in your logs. Version 2 introduced the list axis, the first that can
soften advice; version 3 moved the account_takeover login thresholds onto the
scale of the account-takeover verdict score, so the same visit may get deny where
version 2 gave challenge, and the other way round.
Guidance is additive: new scenarios arrive as new keys without breaking the
contract. The later phase wins, except for partial advice: a delivery computed
on an incomplete set of inputs is marked "partial": true, and partial advice does
not override complete advice received earlier for the same request_id. In an
ordinary delivery the partial field is absent entirely.
Exact thresholds are deliberately not documented. Advice that can be
reverse-engineered into a score stops being a defence. There is exactly one
deliberate exception: account_assessment.verdict.threshold, the decision boundary
of the account-takeover verdict described below.
account_takeover eventBusiness and Enterprise only; on lower plans no delivery is created, even if a
webhook is subscribed to this event. The body is the full identification envelope
for your plan plus an account_alert block and the account_assessment block
described in the next section, delivered at most once per visit:
{ "version": 3, "event": "account_takeover", "event_id": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31:ato", "request_id": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31", "phase": "beacon", // the alert is raised from a beacon; only the event_id says "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}Why type carries a version. The construction behind the score has changed
before: the scale and the basis of the verdict. behavior-drift/2 is the first
versioned construction. If you calibrated your own rules on the number, treat a
change of this value as a signal to re-check them.
account_alert.drift_score and identification.drift_score are the same
number (since 2026-10-03): the smoothed behavior score the verdict was made on,
measured against the account owner's ring of past trusted windows. Before that date
identification.drift_score carried a raw distance on a different scale — do not
mix values across the date. When a window was not judged, the field is absent rather
than zero. Use account_assessment.verdict when you need the number together with
the threshold it was compared against.
In v1 the block is accountAlert with type, linkedId and drift, and there is
no assessment block. In v2 the alert renames two fields — linkedId → accountId
and drift → driftScore — and adds accountAssessment; v3 uses the snake_case
names above. Update your handler when you switch versions, or your account-takeover
logic will silently stop seeing the data.
account_assessment eventBusiness and Enterprise only. Requires an explicit subscription: * does not
include it.
Without this event, the absence of an alert means two different things at once: either we assessed the session against the account owner's profile and it matched, or we could not assess it at all — the owner's profile is not ready, the window was too sparse, or the traffic was not a person. Both look like silence, and silence reads as safety. It usually is not: on a full production day in September 2026 we abstained from a verdict on 73% of windows and 80% of accounts. A process built on "no alert means fine" is built on a state we mostly do not have.
{ "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 is never absent and never empty:
state | Meaning | What to do |
|---|---|---|
assessed_clear | Judged; behavior matches the owner | Nothing |
assessed_alert | Judged; behavior diverges | Step-up — the account_takeover alert carries the same verdict |
not_assessed | No verdict was made | Do not treat as clean; fall back to your own signals |
reason (only with not_assessed):
reason | Meaning |
|---|---|
profile_not_ready | The owner's reference currently cannot produce a verdict for this account. Treat it as a state, not a stage: it may never change, so do not wait |
profile_learning | The reference is still being accumulated |
window_too_sparse | A person was there, but the window carried too little interaction |
not_computable | The window and the reference had no informative axes in common |
bot_traffic | There was enough data, and there was no person to judge |
Since 2026-10-04 18:00 UTC, window_too_sparse and not_computable are no longer
issued for an owner whose reference is ready — such a window is reported as
profile_not_ready. The two reasons stay in the list because earlier deliveries
carry them: if your handler branches on them, route profile_not_ready the same
way, and do not compare rates of these reasons across that date.
state and reason are not gated by plan. verdict is Business+, like
drift_score.
The verdict block is present only with assessed_clear and assessed_alert.
With not_assessed the block is absent rather than filled with zeros — a score of
0 next to a threshold of 0 would read as "behavior matched exactly".
| Field | Meaning |
|---|---|
severity | low or high — two bands, deliberately: a middle band would need a second threshold on the same scale |
score | The value the verdict was made on |
threshold | The value it was actually compared against |
scale | How the score is built: manhattan-normalized is d/(1+d) in a normalized behavioral space, where 0 means an exact match |
basis | ring — distance to the nearest of the owner's past trusted windows; centroid — distance to their averaged profile |
windows | How many windows were aggregated into the score |
score and threshold are always on the same, named scale, so the pair reproduces
the decision: the alert fires exactly when score > threshold.
How often it arrives. At most one delivery per state per visit — in practice one
per visit that carries a linked_id, not one per behavioral window. A state can
change inside one visit — for example, the reference finishes learning and
not_assessed becomes assessed_clear — and then you receive both, in order. That
transition is possible, not promised: profile_not_ready may persist for the whole
life of the account.
What it does not promise. The accounts protected best are active users with long sessions and a full reference profile; the ones protected worst are infrequent users, for whom a takeover is more dangerous. This is a property of the construction, not a threshold that can be tuned. The event reports a behavioral divergence from a reference — it is not a claim to catch account takeover in general.
attack_detected eventThe bot-spike alert arrives in the common v3 envelope with an attack block. It has
no identification fields — this is a workspace-level event:
{ "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 on payload version 1 receive the historical flat alert schema — it does not change.
login_risk, trusted_device_enrolled and trusted_device_revoked eventsDelivered only on an explicit subscription by name — * does not include
them — and only to webhooks on payload version 2 or 3; version 1 has no body for
them. They are described in full in
Login Risk, "Webhooks"; in short:
login_risk is sent when POST /v2/logins/assess returns
challenge or review (never on allow, deny or not_assessed; deny, which
comes only from a self-exclusion, is not sent as a webhook), except a failed
attempt whose every reason is a bot visit or a burst (neutral reasons aside). Its
login_risk block is the stored assessment, in snake_case, exactly as the
synchronous response gave it, without calculation_time and
idempotent_replay. Event id: login-risk:<id>, where <id> is our identifier
of the stored record — take your own assessment_id from the body.trusted_device_enrolled and trusted_device_revoked are sent on every
enrollment, renewal and revoke of a trusted device. Their trusted_device
block — user_id, device_ref, enrolled_at, expires_at, revoked_at,
revoked_by (api, dashboard or recovery) — is a snapshot at the moment
of the event. recovery means Tracio revoked the device after you reported the
outcome executed of a password recovery. Event id: trusted-device:<n>.allow, deny, block and not_assessed assessments send nothing. deny is
not sent as a webhook (it comes only from your own self-exclusion mark), and
neither is block: the stream of block answers during an attack is replaced by
credential_stuffing_campaign. A failed attempt (login_status: "failed") whose
reasons are all automation_on_login, failed_login_burst_device,
failed_login_burst_network or account_targeted (together with
trusted_device, first_device, impossible_travel_anonymized,
credential_exposed_password and credential_stuffing_campaign) does not send
login_risk. If the attack opened a campaign (Business+), it is reported by
credential_stuffing_campaign; nothing replaces the event on Pro, where there
are no campaigns. A successful login and an assessment with any other reason (for
example new_device, ato_alert or impossible_travel) send login_risk as
before, and account_compromise_suspected does not depend on this rule. A failed
attempt with failure_reason: "unknown_account" sends nothing, because no
login is stored for it.
They are sent by a background relay, up to about 5 seconds after the call, and
carry no X-Tracio-Request-Id header — use login_risk.request_id to find the
visit. The webhook is a notification for audit and alerting; the decision itself is
the synchronous response.
{ "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" }}recovery_risk and recovery_hold_released eventsDelivered only on an explicit subscription by name — * does not include
them — and only to webhooks on payload version 2 or 3. They are described in full
in Password Recovery, "Webhooks"; in short:
recovery_risk is sent when POST /v2/recoveries/assess
returns challenge, hold or review (never on allow, deny or a null
recommendation, nor when every reason is recovery velocity, neutral reasons
aside). Its recovery_risk block is the stored assessment, in snake_case,
exactly as the synchronous response gave it, without calculation_time and
idempotent_replay. Event id: recovery-risk:<id>.recovery_hold_released is sent when an operator releases a hold in the
dashboard. Its recovery_hold_released block carries recovery_id, user_id,
hold_until, released_at and released_by (dashboard). Event id:
recovery-hold-released:<id>.recovery_risk is not sent for an assessment whose reasons are all
recovery_velocity_account, recovery_velocity_device or
recovery_velocity_network (together with trusted_device, first_device and
impossible_travel_anonymized); bot_traffic and any other reason send it as
before. recovery_hold_released is always sent.
They are sent by a background relay, up to about 5 seconds after the call, and
carry no X-Tracio-Request-Id header. The plan does not throttle them: Pro
receives them as well.
account_compromise_suspected and credential_stuffing_campaign eventsBusiness+. Delivered only on an explicit subscription by name — * does not
include them — and only to webhooks on payload version 2 or 3; version 1 has no
body for them. They are described in full in
Login Risk, "Credential stuffing"; in
short:
account_compromise_suspected is sent for every assessment that carried an
account_action (step_up, force_password_reset, revoke_sessions or
temp_lock). Its account_compromise block holds the action, user_id,
assessment_id, reasons and campaign_id. Event id:
account-action:<action_id>.credential_stuffing_campaign is sent when a campaign starts (started),
at most once per 15 minutes while it lasts (ongoing), and when it ends
(ended). Its credential_stuffing block holds the scope, the counters and
the busiest devices and ASNs — never a login, an IP address or a network key.
Event id: stuffing-campaign:<campaign_id>:<n>.Neither is a visit event: no X-Tracio-Request-Id header. A block
recommendation of the assess API is not sent as a webhook; during an attack the
credential_stuffing_campaign event takes its place.
affiliate_threshold_crossed eventDelivered only on an explicit subscription by name — * does not include it —
and only to webhooks on payload version 2 or 3. Every 15 minutes TRACIO recomputes
the quality score of each affiliate with enough data and sends the event when its
recommendation gets worse: none → review, none → hold or review → hold. An
improvement sends nothing and lets the next worsening be reported again. The event
belongs to the workspace: it goes to the subscribed webhooks of every environment and
carries no X-Tracio-Request-Id header. Event id:
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 are the affiliate's shares over the last 90 days, the same ones the
dashboard report shows: the share of registrations that reached a first deposit
(reg_to_ftd), the share of players still active 14 days after registration
(active14_share), and the shares of conversions with a duplicate device or person,
from a fraud ring, from bonus hunters, from a datacenter, VPN or bot, labeled as a
chargeback or as affiliate fraud, and without a found visit. TRACIO only recommends —
the hold itself and any payout decision stay in your affiliate platform. On payload
version 2 the same body has camelCase keys: the block is affiliateThreshold, with
affiliateId, previousRecommendation, qualityScore and so on.
transaction_state_changed eventBusiness and above. Sent when the outcome of a transaction you sent to
POST /v2/transactions changes: the rules decided REVIEW or DECLINE (an
APPROVE sends nothing), an analyst sent the transaction to review in the dashboard,
or a label was set, replaced or removed. Use it to hold a bonus while a claim is
under review and to withhold or release it once the outcome is settled, without
polling. * includes this event; it is delivered only to webhooks on payload
version 2 or 3. A webhook bound to an environment receives it only for that
environment.
{ "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 }}| Key | Meaning |
|---|---|
effective_state | The outcome to act on: the analyst's or the label's state when one is set, otherwise state |
recommendations | What to do with the bonus, derived from effective_state |
label, label_source, label_at | The current label, where it was set (api or dashboard) and when; all three are null when the transaction has no label |
previous_effective_state | effective_state before this change; null for the event sent on the automatic decision |
The block shows the transaction as it is when the event is sent: if two changes
follow each other quickly, both events carry the latest state, each with its own
previous_effective_state and timestamp. Order is not guaranteed — sort by
timestamp, and read the transaction through the API for its current state. Event
id: txn-state:<id>:created for the automatic decision and txn-state:<id>:<n> for
every later change. The event does not say who set a label — only where it came from.
reputation_changed eventBusiness and above. Sent when the cross-customer reputation of a person your
organization has seen moves to another band (clean → suspicious, for example).
It requires the person layer, which currently runs in observation mode — so the
event fires only for workspaces where cross-device identity resolution is enabled.
This is a person-level event: it has no request_id and no visit blocks.
{ "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 }}The block key is reputation_change, not reputation: the latter is taken by
reputation in the context of a specific visit, and the two are different things.
Schema 1 delivers the historical flat form — the same fields at the top level.
Every delivery includes an X-Tracio-Signature header:
X-Tracio-Signature: t=1710432000,v1=5257a869e7ecebed…t is the Unix timestamp (seconds) when the request was signed.v1 is the hex-encoded HMAC-SHA256 of "<t>.<rawRequestBody>", keyed with your
webhook secret.The timestamp is part of the signed content, which gives replay protection.
Two things to get right, or verification fails in production:
v1= value. During a secret rotation the header
carries two signatures, and a parser that keeps only one of them will reject
valid deliveries for the whole rotation window.// 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")})Schema 2 and 3 deliveries additionally carry X-Tracio-Signature-Ed25519
(t=<unix>,kid=<id>,v1=<base64>). Both sides know the HMAC secret, so HMAC proves
the sender knows the secret but not that TRACIO originated the request; the
asymmetric signature does. Public keys are published at
https://api.tracio.ai/.well-known/webhook-keys, keyed by kid: read the
public_key field. The legacy alias publicKey carries the same value and will be
removed on 2027-04-12.
Test deliveries sent from the dashboard are signed with HMAC only — the platform
private key lives on the delivery nodes and is deliberately not available to the
dashboard. A verifier that hard-requires Ed25519 must let test deliveries
through (they carry a :test suffix on event_id), otherwise testing from the
dashboard fails while production is healthy. The same caution applies to format
checks: a test delivery carries request_id in the form test_<hex> and the
literal test_visitor as visitor_id, so a handler that validates those against
the production shapes will reject a delivery that is otherwise well formed.
After a rotation both secrets stay valid for 24 hours and the header carries both signatures, so you can update your configuration without losing deliveries. The Revoke now action cuts the window short. Update the secret on your side within 24 hours: once the window closes the old secret stops matching, and if your endpoint answers an invalid signature with a 4xx, five such responses in a row disable the webhook.
| Header | Description |
|---|---|
Content-Type | application/json |
X-Tracio-Signature | t=<unix>,v1=<hmac_sha256_hex> — two v1= during a rotation window |
X-Tracio-Signature-Ed25519 | Platform signature, t=<unix>,kid=<id>,v1=<base64> (v2 and v3 only) |
X-Tracio-Event-Id | Delivery identifier — the idempotency key |
X-Tracio-Request-Id | Visit identifier, matches request_id (v2 and v3 only). Sent only for visit events — identification, account_takeover and account_assessment. attack_detected, reputation_changed, transaction_state_changed, login_risk, trusted_device_enrolled, trusted_device_revoked, recovery_risk, recovery_hold_released, affiliate_threshold_crossed, account_compromise_suspected and credential_stuffing_campaign have no visit, so the header is not sent |
X-Tracio-Event-Type | The event type (v2 and v3 only) |
X-Tracio-Delivery-Attempt | Attempt number, starting at 1 (v2 and v3 only) |
X-Tracio-Payload-Version | 3 or 2 (v2 and v3 only) |
X-Tracio-Webhook-Id | Identifier of the webhook that produced this delivery |
Deliveries may be retried, and a retry carries the same X-Tracio-Event-Id.
Deduplicate on it:
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 that event_id is unique per event, not per webhook: if several webhooks
in the workspace subscribe to the same event, each receives a delivery with the
same identifier. For identification it is built as <request_id>:<phase>, which
is why the three phases of one visit deduplicate independently instead of
collapsing into one. Events without a visit have their own forms — see each event
above.
Respond with 2xx — it is the only sign that a delivery was accepted.
| Response | What happens |
|---|---|
2xx | Delivery complete |
429 Too Many Requests | Not counted as a failure and does not spend an attempt; a longer Retry-After is honored |
408, 425, 5xx, dropped connection | Retried with a growing pause |
410 Gone | The endpoint is treated as removed — the webhook is disabled immediately |
Other 4xx | Retried, but five in a row disable the webhook — 400/401/404 are not cured by retrying |
Retry schedule: 5s → 30s → 2min → 10min → 30min → 2h → 6h (8 attempts). The first retries fit inside a minute, so a brief restart of your service does not cost you a notification. Each pause is randomized between half and the full value so retries do not fire in a single volley after an outage.
Auto-disable requires both a threshold (20 consecutive failures, or 5 configuration errors) and at least 15 consecutive minutes of failures — a brief restart cannot kill the integration even if many deliveries were queued. A gap longer than 15 minutes restarts the count. The dashboard shows the reason, with the response code and error text, and a Re-enable button that resets the counters.
| Plan | Webhooks per workspace |
|---|---|
| Free | Not available |
| Pro | 5 |
| Business | 20 |
| Enterprise | 100 |
Endpoints must be https with a public IP — private and loopback addresses are
rejected, including on a redirect — and no more than two redirects deep.
Only 307 and 308 redirects are followed. 301, 302 and 303 instruct
the client to switch to GET and drop the body, so a delivery does not follow them
and the attempt counts as failed. If your load balancer normalizes the URL (adding
www or a trailing slash), point the webhook straight at the final URL.
Webhooks are managed in the dashboard. The dashboard drives a workspace-scoped
management API, served on the application host (for example
https://app.tracio.ai/api/v1), and the endpoints below are what it calls. Every
webhook endpoint lives under /workspaces/{wsId}.
This is not a server-to-server surface. The management API accepts only your dashboard session JWT, checked against your workspace role (RBAC); a
tracio_sk_…secret key is rejected here. Since that session lives in the browser and expires with it, treat the calls below as a description of what the dashboard does rather than as an integration to automate. For programmatic access from your own backend, use the read-only Data API.
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": [] }'The signing secret is generated by TRACIO and returned once on creation (and on
rotate) under signingSecret. Store it securely — it is the key you use to verify
signatures.
{ "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" }}On subsequent reads the signingSecret is masked (null) — it is revealed only by
create and secret-rotate.
| Method | Path | Description |
|---|---|---|
GET | /workspaces/{wsId}/webhooks | List webhooks |
PATCH | /workspaces/{wsId}/webhooks/{webhookId} | Update url / events / status |
DELETE | /workspaces/{wsId}/webhooks/{webhookId} | Delete a webhook |
POST | /workspaces/{wsId}/webhooks/{webhookId}/test | Send a signed test delivery |
POST | /workspaces/{wsId}/webhooks/{webhookId}/secret/rotate | Rotate the signing secret |
GET | /workspaces/{wsId}/webhooks/{webhookId}/deliveries | List recent delivery attempts |
Return a 2xx as fast as possible and process the payload asynchronously to avoid
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 the Test action on a webhook (or POST .../webhooks/{webhookId}/test) to
send a signed sample payload to your endpoint and confirm it is reachable and
verifying signatures correctly.
For local development, expose your server with a tunnel such as ngrok:
ngrok http 3000# Use the generated URL as your webhook endpoint