コンテンツへスキップ
データ配信

お客様のデータを、判断する場所へ

すべての識別結果は、2つの経路でお客様のシステムに届きます。発生と同時にサーバーへプッシュする経路と、判断するまさにその瞬間にお客様が取りに行く経路です。どちらの経路も同じ数値を運びます。それは約束ではなく、テストによって固定されています。

無料トライアルを開始デモを予約
2つの経路

プッシュか、プルか

Webhookはイベントが起きたそばからお客様へプッシュします。Data APIは、答えが必要になった瞬間に問い合わせるためのものです。多くのチームは両方を併用します。記録と反応にはWebhookを、処理の途中での確認にはData APIを使います。

Webhook — リアルタイムのプッシュ

何かが起きた瞬間に、署名付きのJSONイベントをお客様のエンドポイントへPOSTします。訪問者が識別されたとき、アカウント乗っ取りが検知されたとき、ボット攻撃が始まったとき。ポーリングもスケジューリングも不要です。

適した用途：すべての訪問の記録、攻撃への対応、データウェアハウスやSIEMへの取り込み。

イベントからお客様のエンドポイントまで、p50配信レイテンシは44〜140ms。

Data API — 必要なときのプル

サーバー間で使うプライベートなAPIです。お客様のバックエンドがシークレットキーで認証し、判断するその瞬間に、当社が訪問者について把握している内容をそのまま読み取ります。一般的にはログインや決済のハンドラの中で使われます。

適した用途：カードに課金する前、登録を承認する前、アカウントを解放する前のインラインチェック。

Proプラン以上でご利用いただけます。

Webhook

4種類のイベント、1つのエンベロープ

どの配信も同じエンベロープで届き、イベント種別はボディとX-Tracio-Event-Typeヘッダーの両方に入ります。そのため、1つのハンドラで4種類すべてをルーティングできます。

訪問者を識別

中核となるイベントです。訪問がスコアリングされたことを表し、訪問者ID、ブラウザとOS、地理とネットワーク、ボット判定、リスク判断を運びます。配信はフェーズに分かれ、ページ読み込み時のプライマリイベントに続き、遅れて届いた証拠が判定を変えた場合にlateフェーズまたは訂正フェーズが送られます。フェーズ同士はrequestIdで突き合わせてください。

identification

アカウント乗っ取り

ある訪問でアカウント乗っ取り検知器が発動したことを表します。既知のアカウントの背後にあるデバイスが、そのアカウントの持ち主のデバイスに見えなくなった状態です。識別イベントのボディの中に隠れるのではなく、アカウントの文脈を添えた独立したイベントとして届きます。

account_takeover

ボット攻撃

ワークスペースに対する自動化トラフィックの急増です。これだけは背後に訪問がありません。ワークスペース単位のアラートであるため、訪問関連のブロックは、スコアがゼロの空の殻として届くのではなく、ボディからそのまま省かれます。

attack_detected

レピュテーションの変化

プロファイルがレピュテーションのバンド間を移動しました。エンベロープは攻撃アラートと同じで、訪問を伴わないプロファイル単位のイベントとして、新しいバンドと直前のバンドを運びます。

reputation_changed

配信の例（抜粋）

これはベースとなるボディです。Proでは訪問ベロシティが、Businessでは判定の理由コード、行動シグナル、ガイダンス、ブラウザ横断のデバイスデータが、まったく同じ形の上に加わります。ブロックが増えるだけで、既存のパスが動くことはありません。

JSON
{
  "version": 2,
  "event": "identification",
  "eventId": "req_8f21c4:primary",
  "requestId": "req_8f21c4",
  "phase": "primary",
  "visitorId": "3f9a1b2c4d5e6f70",
  "timestamp": "2026-07-30T12:00:00Z",
  "geo": { "country": "DE", "city": "Berlin", "timezone": "Europe/Berlin" },
  "network": { "vpn": true, "proxy": false, "tor": false, "datacenter": false },
  "bot": { "result": "human", "score": 12 },
  "identification": { "confidence": 0.97, "incognito": false },
  "decision": { "action": "suspicious", "riskScore": 65.9 }
}

すべてのリクエストが2つの署名を運ぶ

X-Tracio-Signatureは、署名タイムスタンプと生のリクエストボディを連結したものに対する、Webhookシークレットを鍵としたHMAC-SHA256です。送信者が双方で保持しているシークレットを知っていることを証明します。X-Tracio-Signature-Ed25519はプラットフォーム署名で、well-knownエンドポイントから取得した公開鍵で検証するため、お客様側に保管すべき秘密情報はありません。タイムスタンプが署名対象に含まれていることが、過去に捕捉した配信を再送しても無意味になる理由です。

検証は生のリクエストバイト列に対して行ってください。JSONを再シリアライズするとバイト列が変わり、署名は一致しなくなります。再試行は同じX-Tracio-Event-Idを持つため、これを使って重複を排除してください。

すべての配信に付くヘッダー

Text
X-Tracio-Signature:         t=1753444800,v1=5257a869e7ecebed...
X-Tracio-Signature-Ed25519: t=1753444800,kid=k1,v1=0Zx0M0n8...
X-Tracio-Event-Type:        identification
X-Tracio-Event-Id:          req_8f21c4:primary
X-Tracio-Delivery-Attempt:  1
X-Tracio-Payload-Version:   2
信頼性

イベントを失わないように作られている

配信は専用のフリートで動作し、真実の源はプロセスのメモリではなくキューです。これがat-least-once配信を現実のものにしています。配信ノードが処理の途中で落ちても、イベントはキューに残っており、別のノードが引き取ります。

単一Webhookあたりの毎秒イベント数。7月の再構築前はおよそ50でした
44–140 msイベントからお客様のエンドポイントまでのp50配信レイテンシ
間隔を広げながらの配信試行回数。最大8.7時間にわたって分散されます
負荷をかけた状態で配信ノードを停止させる訓練において、90,000件のイベントのうち配信された割合

実際の障害に合わせた再試行

5秒、30秒、2分、10分、30分、2時間、6時間。最初の数回は1分以内に届くため、サービスの短い再起動でお客様が失うものはありません。各待機時間は表記値の半分から表記値までの間でランダムに選ばれるため、障害明けに再試行が一斉に押し寄せることもありません。

誤作動しない自動無効化

Webhookが停止されるのは、失敗が閾値に達し、かつその状態が15分以上連続して続いた場合だけです。再起動中に溜まった配信の一時的な失敗で連携が止まることはありません。410 Goneの場合は即座に無効化されます。ダッシュボードには理由、レスポンスコード、再有効化ボタンが表示されます。

切れ目のないシークレットローテーション

ローテーション後は24時間、両方のシークレットが有効なままで、ヘッダーは両方の署名を運びます。どちらか一方が一致すれば十分です。切り替えと競争するのではなく、この猶予期間の中で設定を更新してください。すぐに無効化したい場合は「今すぐ失効」で猶予を打ち切れます。

読める配信ログ

レスポンスコード、所要時間、エラーテキストを含むすべての試行が、ダッシュボードのWebhookごとに表示されます。その隣にはテスト実行があり、署名付きのサンプルペイロードをお客様のエンドポイントに送れるので、本番に出す前に検証処理を確認できます。

Data API

判断するその瞬間に問い合わせる

api.tracio.ai上で提供される、サーバー間のプライベートAPIです。お客様のバックエンドがシークレットキーで認証し、自社のデータを読み取ります。CORSヘッダーは意図的に一切返しません。シークレットキーはワークスペース内のすべてへのアクセスを与えるものであり、ブラウザに渡ってはならないからです。Proプラン以上でご利用いただけます。

メソッドパス戻り値
GET/v1/visitors/{visitorId}訪問者のサマリー。初回と最終の観測、訪問回数、ユニークなIPと国、ブラウザとデバイス、リスク履歴、そして最新セッション。
GET/v1/visitors/{visitorId}/sessionsカーソルページネーション付きのセッション一覧。期間、ボット判定結果、最小リスクスコアで絞り込めます。
GET/v1/visitors/{visitorId}/sessions/latest最新セッションを、一覧のエンベロープなしで単一のオブジェクトとして返します。
GET/v1/sessions/{requestId}特定の1セッション。visitorIdを併せて渡すと、履歴全体ではなく訪問者インデックス経由で検索されます。
GET/v1/visitors/{visitorId}/velocityウィンドウ内の活動（1h、24hまたは7d）。訪問回数、いくつのIPから、いくつの国にまたがり、いくつのアカウントの下で行われたか。

決済時に訪問者を確認する

典型的な呼び出しです。決済ハンドラの中で、カードをオーソリする前に実行します。1リクエストで1つの答えが返り、metaブロックには実際に得られた期間が示されます。6か月分を要求してもプランの保持期間が30日であれば、30日分を返し、そのことを明示します。

リクエスト

bash
# Inside your checkout handler, before you authorize the card
curl -s -H "Authorization: Bearer $TRACIO_SECRET_KEY" \
  "https://api.tracio.ai/v1/visitors/3f9a1b2c/velocity?window=24h"

レスポンス

JSON
{
  "window": "24h",
  "events": 128,
  "uniqueIps": 4,
  "uniqueCountries": 2,
  "uniqueAccounts": 1,
  "meta": { "plan": "business", "retentionDays": 30 }
}

どこでも同じ数値

ダッシュボードで65.9と出た訪問は、Data APIでも65.9、Webhookのボディでも65.9です。2つの独立した描画はずれていく可能性があります。スケールの違いは典型的な例で、片方が0.93を返し、もう片方が93を返すといったことが起こります。そこでパリティテストが1件の訪問を組み立て、両方の経路で描画し、生のJSON上で公開フィールドを比較します。一致は主張ではなく、強制されています。

ガイダンス — Business以上

数値だけでなく、助言を

スコアは当社が何を見たかを伝えます。ガイダンスは、それに対して何をすべきかを伝えます。対象は実際にコストが発生する4つの判断で、バージョン管理されたルールによって算出され、その根拠が添えられます。

決済を受けるか？

カードをオーソリする前に、リスク、不正レピュテーション、ボット判定を重み付けします。

登録を受け入れるか？

使い捨てアカウントが生まれる前に捕まえます。ここでは複数アカウント不正とレピュテーションの比重が最も大きくなります。

ログインを通すか？

その訪問でアカウント乗っ取り検知器が発動していた場合、自動的に厳しくなります。

コンバージョンとして数えるか？

本物の紹介を、自己紹介や報酬目当てのボットと切り分けます。

4語の語彙

allow対応すべきものはありません。
challenge第2要素の確認を求めてください。
review人の確認のために保留してください。
denyそのまま拒否してください。

各シナリオには4つの答えのいずれかが返り、あわせてそれが下された根拠、すなわち決め手となった軸が固定語彙から示されます。ボット、リスク、不正レピュテーション、行動、複数アカウント不正、アカウント乗っ取り、ネットワーク、アフィリエイトパターン。シグナル名も重みも閾値も一切見ることなく、どの軸が助言を動かしたかが常に分かります。

1つの計算、3つの経路

同じガイダンスブロックがWebhookに乗り、Data APIで応答し、ダッシュボードの訪問者カードに描画されます。ルールセットは1つ、結果も1つで、お客様側での突き合わせは不要です。全体値ではなく、ご自身のシナリオに対応する助言を読んでください。全体値は4つのうち最も厳しいものを取っただけの、ダッシュボード向けの要約であり、決済の判断材料ではありません。ルールのバージョンはペイロードに含まれるため、ルールの変更は、助言のずれから推測するものではなく、気づけるものになっています。

JSON
"guidance": {
  "version": 1,
  "overall": "review",
  "payment": "review",
  "registration": "challenge",
  "login": "allow",
  "affiliate": "allow",
  "basis": ["risk", "fraud_reputation"]
}
組み込み

フロントエンドに5つのSDK、バックエンドに2つの経路

ブラウザ側は5つのSDKとして提供されます。バニラJavaScript、React、Vue 3、Angular、Svelte 5です。サーバーサイドSDKはありませんが、これは意図的なものです。お客様のバックエンドは、署名付きWebhookとData APIを通じて素のHTTPで連携します。署名検証は当社が公開しているリファレンスベクターに対して十数行で書けますし、サーバーの依存関係ツリーの中で更新し続けるものが増えることもありません。

ブラウザSDK
JavaScriptReactVue 3AngularSvelte 5
SDKを見るAPIリファレンスWebhookドキュメント
FAQ

よくある質問

半日で組み込めます

ダッシュボードでWebhookを作成し、お客様のエンドポイントを指定して、テストを実行してください。当社のリファレンスベクターに対して署名検証が通れば、難しいところは終わりです。

無料トライアルを開始デモを予約