Webhookは識別イベントをリアルタイムでサーバーに配信します。訪問者が識別される
たびに、TRACIOは構成されたWebhook URLへHTTP POST リクエストを送信します。
リクエストボディがそのままイベントペイロードです。
また、遅延判定 — ページの読み込み後に、訪問者の挙動によって自動化であることが 判明したもの — を届ける唯一のチャネルでもあります。
設定はダッシュボードの設定 → Webhookで行います。WebhookにはProプラン以上が 必要です。
| イベント | タイミング | プラン |
|---|---|---|
identification | すべての訪問で — primary、late、correction の各フェーズ | すべて |
account_takeover | アカウント上の挙動が所有者のプロファイルと一致しなくなったとき | Business以上 |
account_assessment | アカウントのアカウント乗っ取り評価の状態: 判定済みで問題なし、判定済みで乖離あり、または判定なし | Business以上 |
attack_detected | サイト上でのボットの急増 | Business以上 |
reputation_changed | リンクされた人物のレピュテーションが別の帯に移ったとき | Business以上 |
transaction_state_changed | POST /v2/transactions に送信した取引の結果が変わったとき | Business以上 |
login_risk | POST /v2/logins/assess によるログイン評価が challenge または review で終わったとき | すべて |
trusted_device_enrolled | デバイスがアカウントの信頼済みデバイスになった、またはその信頼が更新されたとき | すべて |
trusted_device_revoked | デバイスの信頼が取り消されたとき — APIから、またはダッシュボードから | すべて |
affiliate_threshold_crossed | アフィリエイトに対する推奨が悪化したとき(none → review、none → hold、review → hold) | すべて |
イベント名はアンダースコアで構成され、ドットは決して使いません — visitor.created や
session.created のようなものは存在しません。
Webhookは特定のタイプを購読します。別に用意された値 * は「今後追加されるものも
含む、すべてのタイプ」を意味します。例外は5つのタイプです: * には
account_assessment、login_risk、trusted_device_enrolled、
trusted_device_revoked、affiliate_threshold_crossed が含まれません — それぞれを
明示的に指定してください。 account_assessment は検出結果ではなくカバレッジを
報告するため、linked_id を伴う訪問1回につきおよそ1回届きます — 他のイベントとは
桁の違う量です。ログインリスクとアフィリエイトのタイプは、それらのAPIを呼び出す
統合にとってのみ意味があります。これらのイベントが存在する前に設定したワイルドカードは、
それらを受け取ることへの同意ではありません。
未知のタイプは購読の作成・編集時に 400 で拒否されるため、打ち間違いによって
「何も発火しないWebhook」が黙って残ることはありません。
identification イベントのフェーズ1回の訪問で、同じ request_id を共有する最大3件の配信が生成されます:
primary — ページ読み込み時の最初の判定。late — およそ9秒後、時間のかかるチェックが揃った時点でのエンリッチメント。correction — 挙動(ポインター、キーボード、スクロール)に基づく訂正。request_id で相関付けし、phase で区別します。後のフェーズが優先されます:
primary が human と述べ、correction が bot と述べている場合、正しい答えは
後者です。
到着順に依存しないでください。 各フェーズは独立して、それぞれ独自のリトライ
スケジュールで配信されます — primary がリトライに入っている間に late が初回で
成功すれば、逆の順序で受け取ることになります。優先関係は受信時刻ではなく phase
フィールドから判断してください。
identification イベントのフェーズはこの3つだけです。ただし、もう1つの値が届きます:
account_takeover と account_assessment は phase: "beacon" を運びます。どちらも
セッションの挙動ビーコンから発せられるためです。
ここで生じる食い違いに注意してください。冪等性に影響します。本番の identification
配信では event_id はちょうど <request_id>:<phase> になりますが、他の配信は
この式から外れます。account_takeover では <request_id>:ato であり、サフィックスは
リテラルの ato であって phase フィールドの値ではありません — また
account_assessment では <request_id>:ato-state-<state> です。ダッシュボードから
送られるテスト配信では <request_id>:test になりますが、そのボディの phase は
依然として primary を示します — さらにスキーマ1のボディには phase フィールド
自体が存在しないため、そのサフィックスが現れる場所はヘッダーだけです。event_id は
そのまま冪等性キーとして使い、request_id と phase から組み立て直すことは決して
しないでください。自分が扱う値に一致させ、それ以外は配信を拒否するのではなく
無視してください。
訪問を持たないイベントもあります: attack_detected(ワークスペースレベル)、
reputation_changed(人物レベル)、transaction_state_changed(取引レベル)、
login_risk、trusted_device_enrolled、trusted_device_revoked(アカウント
レベル)、そして affiliate_threshold_crossed(アフィリエイトレベル)です。これらは
request_id も visitor_id も持たず、browser、geo、bot、decision のブロックも
ありません — これらのキーは単に存在せず、X-Tracio-Request-Id ヘッダーも同様です。
これに対して account_takeover と account_assessment は特定の訪問から生成され、
ご利用のプランに応じた識別ボディ一式を運びます。すべてのイベントを1つのハンドラーで
解析する場合は、訪問に関するフィールドに触れる前に event を確認してください。
新規のWebhookはペイロードバージョン3を使用します。バージョン1または2の既存の Webhookは、選択したバージョンのままです。古い2つのスキーマはどちらも凍結されて おり、2027-04-12に削除されます。移行するには、ダッシュボードのWebhookカードで バージョン3を選択してください。
| バージョン | 状態 |
|---|---|
1 | 凍結。2027-04-12に削除 |
2 | 凍結。2027-04-12に削除 |
3 | 新規のWebhookの既定値。snake_caseのキー |
バージョン3はバージョン2と同じフィールドと値を運び、キーはsnake_caseで、トップ
レベルに version: 3 を持ちます。署名アルゴリズムとヘッダーは変わりません
(X-Tracio-Payload-Version: 3)。お客様自身の fields 辞書の中のキーはお客様の
データであり、名前は変更されません。
| 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", // ビデオアダプターのモデル名。正規化済み。不明な場合は存在しない "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トラフィックと生のネットワーク経路が別々のネットワークから出ている }, "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}ゼロ値と空の値は省略されます。 ゼロ値を持つ文字列・数値フィールド(たとえば人間に
対する bot.type や bot.antidetect_score: 0)はJSONに存在しません — スキーマで
必須にせず、ネストされたブロックは防御的に読み取ってください。
bot.score と decision.risk_score は、小数第1位までの**0..100**スケールの小数です
— 同じ訪問についてダッシュボードとData APIが報告するのとまったく同じ数値です。
(凍結されたv1スキーマでは単位が異なり、それぞれ 0..1 の割合と 0..255 です。)
bot.type は、認識されたボットの名前、検証済みのAIエージェント(ai_agent:<vendor>)、
またはファミリーのラベルのいずれかです。語彙はボットタイプを
参照してください — 内部のチェック名が公開されることは、どのプランでもありません。
ai_agent:<vendor> は、リクエストがそのベンダーのインフラストラクチャから来たことを
証明したことを意味します — ベンダーが公開する鍵で作られた有効なWeb Bot Auth署名、
またはベンダーが公開するIPレンジ内のアドレスによってであり、User-Agentで名乗っている
だけではありません。AIエージェントを名乗りながら、ベンダーが公開する証明のどれとも
食い違うリクエストは impersonation として報告されます。
| フィールド | 型 | 説明 |
|---|---|---|
version | number | ペイロードスキーマのバージョン(3) |
event | string | イベントタイプ |
event_id | string | 配信識別子 — 冪等性キー。イベントごとに一意で、そのイベントを受け取るお客様のすべてのWebhookで共有され、リトライをまたいで変わりません |
request_id | string | 訪問識別子(UUID)。その訪問のすべてのフェーズで共有されます |
phase | string | primary、late、correction。account_takeover と account_assessment は beacon を運ぶ |
visitor_id | string | 安定した訪問者識別子 |
linked_id | string | クライアントが指定したリンク済み識別子 |
tag | string | クライアントが指定したカスタムタグ |
fields | object | 収集時に訪問に付加されたカスタムフィールド。訪問とともに届いたものだけ — 後からData APIで付加したフィールドは、どのフェーズでもリトライでもWebhookに現れません。キーと値は文字列。訪問がフィールドを運ばなかった場合は存在しない |
timestamp | string | イベント時刻(RFC 3339) |
url | string | イベントがキャプチャされたページURL |
ip | string | クライアントのIPアドレス |
user_agent | string | 生のクライアントuser-agent文字列 |
browser.name / .version | string | 検知されたブラウザ |
os.name / .version | string | 検知されたオペレーティングシステム |
device | string | デバイスクラス(例: desktop、mobile) |
gpu | string | ブラウザが報告するビデオアダプターのモデル(WebGL)。読みやすい名前に正規化される(Intel Iris Xe Graphics、Apple M1 Pro)。ソフトウェアラスタライザーの場合は Software renderer。不明な場合は存在しない |
geo | object | IP位置情報: country、city、lat、lon、timezone |
network | object | vpn、proxy、tor、datacenter(ブール値)と connection_type |
network.proxy_detected | boolean | その訪問のHTTPトラフィックと生のネットワーク経路が別々のネットワークから出ている——ブラウザの前にプロキシまたはVPNがある。同一プロバイダーの2つのアドレス(キャリアNAT、同じVPNの2つ目の出口)は該当しない |
bot.result | string | human、bot、uncertain のいずれか |
bot.type | string | ボット検知時のボット名、検証済みのAIエージェント、またはファミリーのラベル |
bot.score | number | ボットスコア(0〜100) |
identification.confidence | number | 識別の信頼度(0.0〜1.0) |
identification.incognito | boolean | プライベート/シークレットブラウジングのコンテキスト |
decision.action | string | real、fake、suspicious のいずれか |
decision.risk_score | number | 集約リスクスコア(0〜100) |
extensions | array | この訪問で検知されたブラウザ拡張機能。安定したマシン向けスラッグで表される(名前、カテゴリ、ストアへのリンクはダッシュボードとData APIにあります)。何も検知されなかった場合は存在しない |
Pro以上 — 訪問者が時間の経過とともにどう振る舞うか:
{ "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以上 — なぜその判定になったか:
{ "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, // 生のネットワーク経路上で観測された公開アドレス。つまりプロキシまたはVPN // の背後にあるアドレス。そのようなアドレスが観測されなかった場合は存在しない "real_ip": { "address": "203.0.113.7", "country": "NL", "isp": "KPN" } }, "geo": { "isp": "Deutsche Telekom" }, // Linuxマシン上で実測されたデスクトップ環境("Mint 22+"、"Ubuntu"、 // "GNOME"、"KDE")。User-Agentはディストリビューションを表現できない。判定 // できない場合は存在せず、ほとんどのLinux訪問と、Linux以外のすべての訪問が // これにあたる。 "os_environment": "Mint 22+", // その訪問が自身について主張した内容と、独立した検査が実測した内容の対比。 // 詐称が実際に検出されたときにのみ存在する。`real` フィールドが空なのは // 「検査が沈黙した」という意味であり、「確認された」ではない。`gpu` 軸で // は、`claimed.gpu` が主張されたアダプターを、トップレベルの `gpu` フィー // ルドと同じ読みやすいモデル名で保持する。 "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"] } }, // デバイスの事実——訪問者のブラウザがマシンについて報告する内容を、当社側で // サニタイズしたもの。screen: 解像度、色深度、device pixel ratio。locale: // ブラウザ自身が優先する言語とタイムゾーン。IPアドレスから導かれる // geo.timezone とは異なり、両者の食い違いは位置の詐称によく見られる兆候で // ある。client_hints: User-Agent Client Hints——CPUのアーキテクチャとビット // 数、デバイスモデル(Android では、`model` にモデルコード、例: // "SM-A556B"、`device_name` に Google Play デバイスリストのマーケティング // 名、例: "Samsung Galaxy A55 5G")、正確なプラットフォームバージョ // ン。報告するのはChromium系ブラウザのみ。訪問がそうしたデータを運ばな // かった場合、各ブロックは存在しないため、いずれも任意として扱うこと。 "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" }, // ビデオアダプターが自身を仮想であると名乗った場合にのみ存在する。 // hypervisor は閉じた辞書(vmware、virtualbox、parallels、qemu、hyperv、 // bochs、intel-gvt、vgpu)。ブロックがなければ、そのような証拠はないという // 意味である。 "environment": { "virtual_machine": true, "hypervisor": "vmware" }, "decision": { "suspect_score": 4.1 }, "guidance": { "version": 3, "overall": "review" } // see below}理由コードの語彙と severity の意味については
ボット検知を参照してください。
マルチアカウントのフィールド(Business以上)。 ワークスペースでpersonモードが
有効になると、ボディには person_id、reputation ブロック(score、categories、
overall_risk)、linked_accounts_count、linked_visitors_count も含まれます —
訪問者が他の訪問者やアカウントとリンクされているかどうかです。personレイヤーは現在
観測モードで動作しており、本稼働するまでこれらのフィールドはボディに存在しません。
スキーマで必須にしないでください。
guidance は、統合ポイントごとの「どうすべきか」という既成の推奨を運びます。生の
スコアからポリシーを導き出す必要はありません。v3のBusiness以上のすべてのイベントに
含まれ、allow も明示的に示されます:
{ "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 }}各シナリオは allow から始まり、ラダーを上にしか進みません:
allow → challenge → review → deny。シナリオ内では発火した最も厳しい軸が
優先され、overall は4つのシナリオすべての中で最も厳しいものになります。
| 推奨 | 決済 | 登録 | ログイン | アフィリエイト |
|---|---|---|---|---|
allow | 処理する | 作成する | 入室を許可する | コンバージョンを計上する |
challenge | 3-Dセキュア/確認 | CAPTCHA、メールまたは電話での確認 | ステップアップ2FA、再認証 | 活動が確認されるまで疑わしいものとして印を付ける |
review | 処理するが、レビュー待ちに入れる | 制限付きで作成する | 入室を許可し、アラートを上げる | レビューが済むまで支払いを保留する |
deny | 取引を処理しない | アカウントの作成を拒否する | 入室を許可しない | コンバージョンを計上しない |
basis には推奨を決定した軸が並びます — 提案が採用されたものより穏やかだった軸は
リストに入りません。固定のセットを前提にせず、コードで読み取ってください:
軸(basis) | 意味 |
|---|---|
list | 訪問者が enforce モードのワークスペースのリストのいずれかに一致した。allow リストはすべての軸に優先する: すべてのシナリオが allow になり、basis はちょうど ["list"] になる |
rule | 訪問が enforce モードのワークスペースのルールのいずれかに一致した。ルールが動かすのは自分のシナリオの推奨だけで(allow ルールはそのシナリオだけを緩める)、すでにリストが作用した場合はスキップされる |
bot | ボット検知器が自動化であると結論づけた — すべてのシナリオを拒否する |
risk | 訪問の判定と総合リスクスコア |
behavior | 行動バイオメトリクスが十分な信頼度でボットと示している — 拒否ではなく摩擦を加える |
account_takeover | このアカウント上の挙動が所有者のプロファイルと一致しなくなった — ログインは challenge、決済は review |
network | Tor、またはデータセンターから出ているVPN |
affiliate_pattern | 自作の紹介の形 — アフィリエイトのコンバージョンは challenge として保留される |
fraud_reputation, multiaccounting | 訪問者の背後にいる人物のレピュテーションとアカウントのクラスタリング。personレイヤーが本稼働すると現れる |
version はルールセットのバージョンで、ロジックが改善されるたびに上がるため、ログに
残してください。バージョン2では推奨を緩められる最初の軸である list 軸が導入され、
バージョン3では account_takeover のログインしきい値がアカウント乗っ取り判定スコアの
スケールに移されました。そのため同じ訪問でも、バージョン2が challenge を返した
ところで deny になることがあり、その逆もあります。
ガイダンスは追加的です: 新しいシナリオは新しいキーとして届き、契約を壊しません。
後のフェーズが優先されますが、部分的な推奨は例外です: 不完全な入力セットで
計算された配信には "partial": true が付き、部分的な推奨は同じ request_id に
ついて先に受け取った完全な推奨を上書きしません。通常の配信では partial
フィールドは完全に存在しません。
正確なしきい値は意図的に文書化されていません。スコアに逆算できてしまう推奨は、
もはや防御にはなりません。意図的な例外はちょうど1つだけです:
account_assessment.verdict.threshold、つまり後述するアカウント乗っ取り判定の
決定境界です。
account_takeover イベントBusinessおよびEnterpriseのみ。下位のプランでは、Webhookがこのイベントを購読していても
配信は作成されません。ボディは、ご利用のプランに応じた識別エンベロープ一式に
account_alert ブロックと次のセクションで説明する account_assessment ブロックを
加えたもので、1回の訪問につき最大1回配信されます:
{ "version": 3, "event": "account_takeover", "event_id": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31:ato", "request_id": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31", "phase": "beacon", // アラートはビーコンから発せられる。"ato" と言うのは event_id だけ "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}type がバージョンを持つ理由。 スコアの背後にある構成は以前にも変わっています:
判定のスケールと基準です。behavior-drift/2 は最初のバージョン付きの構成です。この
数値で独自のルールを調整している場合は、この値の変化をルールを見直す合図として
扱ってください。
account_alert.drift_score と identification.drift_score は同じ数値です
(2026-10-03以降): 判定の根拠となった平滑化済みの挙動スコアで、アカウント所有者の
過去の信頼済みウィンドウのリングに対して測定されます。この日付より前は、
identification.drift_score は別のスケールの生の距離を運んでいました — この日付を
またいで値を混ぜないでください。ウィンドウが判定されなかった場合、フィールドはゼロでは
なく存在しません。数値を、比較対象となったしきい値と一緒に必要とする場合は
account_assessment.verdict を使ってください。
v1ではこのブロックは accountAlert で、type、linkedId、drift を運び、評価
ブロックはありません。v2ではアラートの2つのフィールドが改名され — linkedId →
accountId、drift → driftScore — accountAssessment が追加されます。v3は上記の
snake_caseの名前を使います。バージョンを切り替える際にはハンドラーを更新してください。
さもないと、アカウント乗っ取りのロジックは黙ってデータを見なくなります。
account_assessment イベントBusinessおよびEnterpriseのみ。明示的な購読が必要です: * には含まれません。
このイベントがなければ、アラートがないことは同時に2つの異なる意味を持ちます: セッションを アカウント所有者のプロファイルと照らして評価し一致したのか、そもそも評価できなかったのか — 所有者のプロファイルが準備できていない、ウィンドウが疎すぎた、あるいはトラフィックが 人間ではなかった — のどちらかです。どちらも沈黙に見え、沈黙は安全と読まれます。しかし たいていはそうではありません: 2026年9月の本番の丸1日で、私たちはウィンドウの73%、 アカウントの80%で判定を見送りました。「アラートがなければ問題なし」の上に築かれた プロセスは、ほとんどの場合私たちが持っていない状態の上に築かれています。
{ "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 が欠けることも空になることも決してありません:
state | 意味 | 対応 |
|---|---|---|
assessed_clear | 判定済み。挙動は所有者と一致 | 何もしない |
assessed_alert | 判定済み。挙動が乖離している | ステップアップ — account_takeover アラートが同じ判定を運ぶ |
not_assessed | 判定は行われなかった | クリーンとして扱わない。お客様自身のシグナルにフォールバックする |
reason(not_assessed の場合のみ):
reason | 意味 |
|---|---|
profile_not_ready | 所有者の基準が、現時点ではこのアカウントについて判定を出せない。段階ではなく状態として扱うこと: 変わらないこともあるので待たない |
profile_learning | 基準はまだ蓄積中 |
window_too_sparse | 人間はいたが、ウィンドウに含まれるインタラクションが少なすぎた |
not_computable | ウィンドウと基準に、情報を持つ共通の軸がなかった |
bot_traffic | データは十分にあったが、判定すべき人間がいなかった |
2026-10-04 18:00 UTC以降、基準が準備できている所有者については window_too_sparse と
not_computable は発行されなくなりました — そのようなウィンドウは profile_not_ready
として報告されます。以前の配信がこの2つの理由を運んでいるため、リストには残っています:
ハンドラーがこれらで分岐している場合は profile_not_ready も同じように振り分け、
この日付をまたいでこれらの理由の比率を比較しないでください。
state と reason はプランによる制限を受けません。verdict は drift_score と同様に
Business以上です。
verdict ブロックは assessed_clear と assessed_alert の場合にのみ存在します。
not_assessed の場合、ブロックはゼロで埋められるのではなく存在しません — threshold
が0の隣に score が0あれば、「挙動が完全に一致した」と読まれてしまうからです。
| フィールド | 意味 |
|---|---|
severity | low または high — 意図的に2段階: 中間の段階には同じスケール上に2つ目のしきい値が必要になる |
score | 判定の根拠となった値 |
threshold | 実際に比較された値 |
scale | スコアの構成方法: manhattan-normalized は正規化された行動空間における d/(1+d) で、0は完全一致を意味する |
basis | ring — 所有者の過去の信頼済みウィンドウのうち最も近いものまでの距離。centroid — 平均化したプロファイルまでの距離 |
windows | スコアに集約されたウィンドウの数 |
score と threshold は常に同じ名前付きのスケール上にあるため、この組で判定を再現
できます: アラートが発火するのは、ちょうど score > threshold のときです。
届く頻度。 1回の訪問につき状態ごとに最大1件の配信 — 実際には、行動ウィンドウ
ごとではなく、linked_id を伴う訪問1回につき1件です。状態は1回の訪問の中で変わる
ことがあります — たとえば基準の学習が終わって not_assessed が assessed_clear に
なる — その場合は両方を順番に受け取ります。この遷移は起こり得ますが、約束されては
いません: profile_not_ready がアカウントの存続期間を通じて続くこともあります。
約束しないこと。 最もよく保護されるのは、セッションが長く基準プロファイルが充実した アクティブなユーザーです。最も保護が弱いのは、たまにしか利用しないユーザーで、彼らに とって乗っ取りはより危険です。これは構成上の性質であり、調整できるしきい値では ありません。このイベントは基準からの行動上の乖離を報告するものであり、アカウント 乗っ取り一般を捕捉すると主張するものではありません。
attack_detected イベントボット急増のアラートは、attack ブロックを持つ共通のv3エンベロープで届きます。識別
フィールドはありません — これはワークスペースレベルのイベントです:
{ "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 }}ペイロードバージョン1のWebhookは、従来のフラットなアラートスキーマを受け取ります — これは変わりません。
login_risk、trusted_device_enrolled、trusted_device_revoked イベントこの3つのイベントは、ログインリスクAPI(POST /v2/logins/assess)とその信頼済み
デバイスに対するお客様自身の呼び出しから生じます。配信されるのは名前による明示的な
購読がある場合だけで — * には含まれません — しかもペイロードバージョン2または3の
Webhookに限られます。バージョン1にはこれらのボディがありません。
login_risk は、評価が challenge または review を返したときに送信されます —
allow、deny、not_assessed では決して送信されません。その login_risk ブロックは
保存された評価で、同期レスポンスが返したものとまったく同じです。イベントID:
login-risk:<id>。<id> は保存されたレコードに対する当社の識別子です — お客様自身の
assessment_id はボディから取得してください。trusted_device_enrolled と trusted_device_revoked は、信頼済みデバイスの登録、
更新、取り消しのたびに送信されます。その trusted_device ブロック — user_id、
device_ref、enrolled_at、expires_at、revoked_at、revoked_by(api または
dashboard)— はイベント時点のスナップショットです。trusted_device_enrolled では
revoked_at と revoked_by は null です。イベントID: trusted-device:<n>。これらは非同期で、呼び出しからおよそ5秒以内に送信され、X-Tracio-Request-Id ヘッダーを
持ちません — 訪問を探すには login_risk.request_id を使ってください。Webhookは監査と
アラートのための通知であり、判定そのものは同期レスポンスです。
{ "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_crossed イベント配信されるのは名前による明示的な購読がある場合だけで — * には含まれません —
しかもペイロードバージョン2または3のWebhookに限られます。TRACIOは15分ごとに、十分な
データのあるアフィリエイトそれぞれの品質スコアを再計算し、その推奨が悪化したときに
イベントを送信します: none → review、none → hold、または review → hold。改善した
場合は何も送信されず、次に悪化したときに再び報告されるようになります。このイベントは
ワークスペースに属します: すべての環境の購読しているWebhookに届き、
X-Tracio-Request-Id ヘッダーを持ちません。イベント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 は直近90日間のアフィリエイトの比率で、ダッシュボードのレポートが示すものと
同じです: 初回入金に至った登録の比率(reg_to_ftd)、登録から14日後もアクティブな
プレイヤーの比率(active14_share)、そして重複したデバイスや人物を持つ、不正リング
からの、ボーナスハンターからの、データセンター・VPN・ボットからの、チャージバックまたは
アフィリエイト不正とラベル付けされた、訪問が見つからなかったコンバージョンの比率です。
TRACIOは推奨するだけです — 保留そのものと支払いに関する判断は、お客様のアフィリエイト
プラットフォームに残ります。ペイロードバージョン2では、同じボディがcamelCaseのキーを
持ちます: ブロックは affiliateThreshold で、affiliateId、previousRecommendation、
qualityScore などを含みます。
transaction_state_changed イベントBusiness以上。POST /v2/transactions に送信した取引の結果が変わったときに送信されます:
ルールが REVIEW または DECLINE と判定した(APPROVE では何も送信されない)、
アナリストがダッシュボードで取引をレビューに回した、あるいはラベルが設定・置換・削除
された場合です。申請がレビュー中のあいだボーナスを保留し、結果が確定したら差し止めるか
解放するのに、ポーリングなしで使えます。* にはこのイベントが含まれます。配信されるのは
ペイロードバージョン2または3のWebhookだけです。環境に紐付いたWebhookは、その環境に
ついてのみこのイベントを受け取ります。
{ "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 }}| キー | 意味 |
|---|---|
effective_state | 対応の基準とすべき結果: アナリストまたはラベルの状態が設定されていればそれ、なければ state |
recommendations | ボーナスをどう扱うか。effective_state から導かれる |
label, label_source, label_at | 現在のラベル、それが設定された場所(api または dashboard)と時刻。取引にラベルがない場合は3つとも null |
previous_effective_state | この変更前の effective_state。自動判定時に送られるイベントでは null |
このブロックはイベント送信時点の取引を示します: 2つの変更が素早く続いた場合、両方の
イベントが最新の状態を運び、それぞれが独自の previous_effective_state と timestamp
を持ちます。順序は保証されません — timestamp で並べ替え、現在の状態はAPIで取引を
読み取って確認してください。イベントID: 自動判定には txn-state:<id>:created、それ以降の
変更には毎回 txn-state:<id>:<n>。このイベントは誰がラベルを設定したかは示さず — どこから
来たかだけを示します。
reputation_changed イベントBusiness以上。お客様の組織が見たことのある人物の顧客横断のレピュテーションが別の帯に
移ったとき(たとえば clean → suspicious)に送信されます。personレイヤーが必要で、
現在は観測モードで動作しているため、このイベントはクロスデバイスのアイデンティティ解決が
有効なワークスペースでのみ発火します。これは人物レベルのイベントです: request_id も
訪問のブロックも持ちません。
{ "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 }}ブロックのキーは reputation ではなく reputation_change です: 前者は特定の訪問の
文脈でのレピュテーションに使われており、両者は別物です。スキーマ1は従来のフラットな
形式 — 同じフィールドをトップレベルに — で配信します。
すべての配信には X-Tracio-Signature ヘッダーが含まれます:
X-Tracio-Signature: t=1710432000,v1=5257a869e7ecebed…t はリクエストが署名されたUnixタイムスタンプ(秒)です。v1 は、Webhookシークレットでキー付けされた "<t>.<rawRequestBody>" の
16進エンコードされたHMAC-SHA256です。タイムスタンプは署名対象のコンテンツの一部であり、これがリプレイ保護になります。
正しく行うべき点が2つあります。外すと本番で検証に失敗します:
v1= の値が一致すれば受け入れてください。 シークレットの
ローテーション中、ヘッダーは2つの署名を運びます。片方しか保持しないパーサーは、
ローテーションの期間を通じて正当な配信を拒否し続けます。// 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")})スキーマ2と3の配信には、追加で X-Tracio-Signature-Ed25519
(t=<unix>,kid=<id>,v1=<base64>)が含まれます。HMACシークレットは双方が知って
いるため、HMACは送信者がシークレットを知っていることは証明しますが、リクエストが
TRACIO発であることは証明しません。非対称署名はそれを証明します。公開鍵は
https://api.tracio.ai/.well-known/webhook-keys で kid をキーとして公開されています:
public_key フィールドを読み取ってください。旧来のエイリアス publicKey は同じ値を
運びますが、2027-04-12に削除されます。
ダッシュボードから送信されるテスト配信はHMACのみで署名されます — プラットフォームの
秘密鍵は配信ノード上にあり、ダッシュボードからは意図的に利用できないように
なっています。Ed25519を必須とする検証処理は、テスト配信を通す必要があります
(テスト配信は event_id に :test サフィックスが付きます)。そうしないと、本番は
正常なのにダッシュボードからのテストだけが失敗します。同じ注意は形式チェックにも
当てはまります: テスト配信の request_id は test_<hex> という形をとり、visitor_id
はリテラルの test_visitor です。したがって、これらを本番の形式に照らして検証する
ハンドラーは、それ以外の点では正しく組み立てられた配信を拒否してしまいます。
ローテーション後、両方のシークレットが24時間有効なままとなり、ヘッダーは両方の署名を 運ぶため、配信を失うことなく設定を更新できます。今すぐ失効アクションはこの期間を 短縮します。お客様側のシークレットは24時間以内に更新してください: 期間が閉じると 古いシークレットは一致しなくなり、無効な署名に対してエンドポイントが4xxを返す場合、 そうした応答が5回続くとWebhookが無効化されます。
| ヘッダー | 説明 |
|---|---|
Content-Type | application/json |
X-Tracio-Signature | t=<unix>,v1=<hmac_sha256_hex> — ローテーション期間中は v1= が2つ |
X-Tracio-Signature-Ed25519 | プラットフォーム署名、t=<unix>,kid=<id>,v1=<base64>(v2とv3のみ) |
X-Tracio-Event-Id | 配信識別子 — 冪等性キー |
X-Tracio-Request-Id | 訪問識別子。request_id と一致(v2とv3のみ)。訪問イベント — identification、account_takeover、account_assessment — でのみ送信される |
X-Tracio-Event-Type | イベントタイプ(v2とv3のみ) |
X-Tracio-Delivery-Attempt | 試行番号。1から始まります(v2とv3のみ) |
X-Tracio-Payload-Version | 3 または 2(v2とv3のみ) |
X-Tracio-Webhook-Id | この配信を生成したWebhookの識別子 |
配信はリトライされることがあり、リトライは同じ X-Tracio-Event-Id を運びます。
これで重複を排除してください:
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")})event_id はWebhookごとではなくイベントごとに一意である点に注意してください:
ワークスペース内の複数のWebhookが同じイベントを購読している場合、それぞれが同じ
識別子を持つ配信を受け取ります。identification ではこの値は <request_id>:<phase>
として組み立てられるため、1回の訪問の3つのフェーズは1つにまとまるのではなく、
それぞれ独立して重複排除されます。訪問を持たないイベントには独自の形式があります —
上記の各イベントを参照してください。
2xx を返してください — 配信が受け入れられたことを示す唯一の合図です。
| 応答 | 動作 |
|---|---|
2xx | 配信完了 |
429 Too Many Requests | 失敗として数えられず、試行も消費しません。より長い Retry-After は尊重されます |
408、425、5xx、接続の切断 | 待機時間を伸ばしながらリトライされます |
410 Gone | エンドポイントは削除されたものとして扱われ、Webhookは直ちに無効化されます |
その他の 4xx | リトライされますが、5回連続でWebhookが無効化されます — 400/401/404 はリトライでは治りません |
リトライのスケジュール: 5s → 30s → 2min → 10min → 30min → 2h → 6h(8回の試行)。 最初のリトライは1分以内に収まるため、サービスの短時間の再起動で通知を失うことは ありません。各待機時間は半分から全量の間でランダム化されるため、障害の復旧後に リトライが一斉に発火することはありません。
自動無効化には、しきい値(連続20回の失敗、または5回の設定エラー)と、 少なくとも15分間連続して失敗が続くことの両方が必要です — 多くの配信がキューに 溜まっていたとしても、短時間の再起動で統合が停止することはありません。15分を超える 間隔が空くとカウントはやり直しになります。ダッシュボードには理由が応答コードと エラーテキストとともに表示され、カウンターをリセットする再有効化ボタンが あります。
| プラン | ワークスペースあたりのWebhook数 |
|---|---|
| Free | 利用できません |
| Pro | 5 |
| Business | 20 |
| Enterprise | 100 |
エンドポイントはパブリックIPを持つ https である必要があります — プライベート
アドレスとループバックアドレスは、リダイレクト先であっても拒否されます — また、
リダイレクトは2段までです。
追跡されるリダイレクトは 307 と 308 のみです。 301、302、303 は
クライアントにGETへの切り替えとボディの破棄を指示するため、配信はこれらを追跡せず、
その試行は失敗として数えられます。ロードバランサーがURLを正規化する場合
(www や末尾のスラッシュの付加)、Webhookは最終的なURLへ直接向けてください。
Webhookはダッシュボードで管理します。ダッシュボードはワークスペーススコープの
管理APIを駆動しており、このAPIはアプリケーションホスト(例:
https://app.tracio.ai/api/v1)で提供されます。以下のエンドポイントは、その
ダッシュボードが呼び出しているものそのものです。Webhookのエンドポイントはすべて
/workspaces/{wsId} の下にあります。
これはサーバー間連携のための面ではありません。 管理APIが受け付けるのは ダッシュボードのセッションJWTだけで、ワークスペース内のロール(RBAC)に 照らして検査されます。
tracio_sk_…のシークレットキーはここでは拒否されます。 そのセッションはブラウザー内に存在し、ブラウザーとともに失効するため、以下の 呼び出しは自動化する連携先ではなく、ダッシュボードが何をしているかの説明として 捉えてください。自前のバックエンドからプログラムでアクセスする場合は、読み取り 専用の 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": [] }'署名シークレットはTRACIOが生成し、作成時(およびローテーション時)に一度だけ
signingSecret として返されます。安全に保管してください — 署名の検証に使う鍵です。
{ "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" }}以降の読み取りでは signingSecret はマスクされます(null) — 公開されるのは作成時と
シークレットのローテーション時のみです。
| メソッド | パス | 説明 |
|---|---|---|
GET | /workspaces/{wsId}/webhooks | Webhookの一覧 |
PATCH | /workspaces/{wsId}/webhooks/{webhookId} | url / events / status の更新 |
DELETE | /workspaces/{wsId}/webhooks/{webhookId} | Webhookの削除 |
POST | /workspaces/{wsId}/webhooks/{webhookId}/test | 署名済みのテスト配信を送信 |
POST | /workspaces/{wsId}/webhooks/{webhookId}/secret/rotate | 署名シークレットの再生成 |
GET | /workspaces/{wsId}/webhooks/{webhookId}/deliveries | 直近の配信試行の一覧 |
タイムアウトを避けるため、できるだけ早く 2xx を返し、ペイロードは非同期で処理して
ください:
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) }}Webhookのテストアクション(または POST .../webhooks/{webhookId}/test)を使うと、
署名済みのサンプルペイロードをエンドポイントへ送信し、到達可能であること、署名を
正しく検証していることを確認できます。
ローカル開発では、ngrok などのトンネルでサーバーを公開してください:
ngrok http 3000# Use the generated URL as your webhook endpoint