Webhook ペイロードリファレンス
送信が検証をクリアすると、フォワーダーは設定済みの webhook URL へ 1 つの POST を送ります。このページは、そのリクエストの正確な契約です。設定の手順については ホスト型認証を設定する を、概念については バックエンドなしで検証する を参照してください。
リクエストラインとヘッダー
フォワーダーは JSON のボディと、これらのヘッダーを伴う POST を送ります：
| ヘッダー | 値 |
|---|---|
content-type | application/json |
accept | application/json |
user-agent | Caputchin-Forwarder/0.1 |
x-caputchin-test | 1、ダッシュボードの 配信をテスト でのみ存在。本物の送信にはなし |
呼び出しはリダイレクトを無効にし、数秒のタイムアウトで送られます。リクエストは署名されません。それを認証するのは webhook URL の秘匿性です。
ボディ
ボディは、2 つのトップレベルキー、caputchin（Caputchin が加える検証メタデータ）と form（あなたが送信したフィールド）を持つ JSON オブジェクトです：
{
"caputchin": {
"site_key": "cpt_pub_...",
"session_id": "...",
"game_id": "caputchin/games/leaf-memory",
"score": 847,
"duration_ms": 4200,
"verified_at": 1748640000000
},
"form": {
"email": "visitor@example.com",
"message": "Hello!"
}
}caputchin オブジェクト
| フィールド | 型 | 意味 |
|---|---|---|
site_key | string | 送信が来た公開 cpt_pub_... キー。 |
session_id | string | 不透明な検証セッション id。相関や重複排除に役立ちます。テスト配信では test_ が接頭につきます。 |
game_id | string または null | 訪問者が遊んだゲーム。検証がゲームなしで走ったときは null。 |
score | number または null | ゲームのスコア。分析のためのクライアントが申告するメタデータで、決して信頼のシグナルではありません。該当しないときは null。 |
duration_ms | number または null | 訪問者がゲームを遊んだ時間、ミリ秒で。クライアントが申告するもので、信頼のシグナルではありません。該当しないときは null（たとえばゲームのない検証）。 |
verified_at | number | Caputchin がトークンを検証したとき、ミリ秒の Unix エポックで。 |
test | boolean（任意） | ダッシュボードのテスト配信でのみ存在し true。本物の送信にはなし。 |
game_id、score、duration_ms は本物の送信でそれぞれ null になり得るので、読む前に null を防いでください。caputchin のフィールドのどれも信頼の判断ではありません。信頼は、リクエストがそもそも届いたことです。検証に失敗する送信は決して転送されないからです。
form オブジェクト
form は、あなたが送信したフィールドの、文字列キーと文字列値の、ちょうどポストされたとおりのフラットなオブジェクトです。ただ 1 つの変更があります。caputchin-token フィールドは配信の前に取り除かれるので、ここには決して現れません。フォワーダーはテキストフィールドだけを受け付けます。ファイルアップロードを運ぶ送信は、いかなる配信の前にも拒否されます。
あなたのハンドラーが返すべきもの
受領を確認するには、どの 2xx ステータスでも返してください。フォワーダーは、非 2xx の応答、タイムアウト、または接続失敗を、失敗した配信として扱い、失敗した配信は再試行されません。配信の健全性は 統計 ページで追ってください。
あわせて読む
- ホスト型認証を設定する：webhook を配線し、テスト配信を発火する。
- バックエンドなしで検証する：概念、プライバシーの姿勢、URL 安全のルール。
- ホスト型認証の統計：配信の成功と失敗を読む。