---
type: reference
title: Webhook 载荷参考
summary: 一个托管验证 webhook 收到的确切请求、体里的每个字段，以及 Caputchin 发送的头。
---

当一次提交通过验证时，转发器会向你配置的 webhook URL 发一个 `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 的保密性即为它的身份验证。

## 体

这个体是一个带两个顶层键的 JSON 对象，`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` 是一个把你提交的字段作为字符串键和字符串值的扁平对象，恰好如所提交的那样，只有一处改动：`caputchin-token` 字段在投递前被剥离，所以它绝不出现在这里。转发器只接受文本字段；一次携带文件上传的提交会在任何投递之前被拒绝。

## 你的处理器应该返回什么

返回任何 `2xx` 状态以确认收到。转发器把一个非 `2xx` 响应、一次超时、或一次连接失败都当作一次失败的投递，而一次失败的投递不会被重试。在 [统计](/docs/hosted-verification/statistics) 页上跟踪投递健康度。

## 另见

- [设置托管验证](/docs/hosted-verification/set-up)：接好一个 webhook 并发一次测试投递。
- [不用后端也能验证](/docs/hosted-verification/overview)：这个概念、隐私姿态，以及 URL 安全规则。
- [托管验证统计](/docs/hosted-verification/statistics)：读投递的成功与失败。