托管验证
Webhook 载荷参考
当一次提交通过验证时，转发器会向你配置的 webhook URL 发一个 POST。这一页就是那个请求的确切契约。设置演练见 设置托管验证；概念见 不用后端也能验证。
请求行与头
转发器发一个带 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（你提交的字段）：
{
"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 响应、一次超时、或一次连接失败都当作一次失败的投递，而一次失败的投递不会被重试。在 统计 页上跟踪投递健康度。