---
type: reference
title: Webhook ペイロードリファレンス
summary: ホスト型認証の webhook が受け取る正確なリクエスト、ボディの各フィールド、そして Caputchin が送るヘッダー。
---

送信が検証をクリアすると、フォワーダーは設定済みの webhook URL へ 1 つの `POST` を送ります。このページは、そのリクエストの正確な契約です。設定の手順については [ホスト型認証を設定する](/docs/hosted-verification/set-up) を、概念については [バックエンドなしで検証する](/docs/hosted-verification/overview) を参照してください。

## リクエストラインとヘッダー

フォワーダーは 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 オブジェクトです：

```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` の応答、タイムアウト、または接続失敗を、失敗した配信として扱い、失敗した配信は再試行されません。配信の健全性は [統計](/docs/hosted-verification/statistics) ページで追ってください。

## あわせて読む

- [ホスト型認証を設定する](/docs/hosted-verification/set-up)：webhook を配線し、テスト配信を発火する。
- [バックエンドなしで検証する](/docs/hosted-verification/overview)：概念、プライバシーの姿勢、URL 安全のルール。
- [ホスト型認証の統計](/docs/hosted-verification/statistics)：配信の成功と失敗を読む。