用一个测试收件箱设置托管验证

到这篇教程结束时，你将有一个能用的联系表单，它的提交由 Caputchin 核验并投递到一个 webhook，而且你将看着一次已核验的提交落进一个你能检视的测试收件箱。我们先用 webhook.site 作为目标，因为它会在你投入到自己的端点之前，先让你看到 Caputchin 发送的确切载荷。

你需要一个 Alpha、Troop 或 Apex 套餐（托管验证不在 Solo 上）、一个站点密钥，以及一个你能编辑表单 HTML 的页面。如果你还没把组件加到一个页面上，那就先去添加组件；这篇教程假定有一个能用的 <caputchin-widget>。

1. 弄一个测试收件箱

在一个新标签页里打开 webhook.site。它立刻给你一个看起来像 https://webhook.site/#!/<uuid> 的唯一 URL，以及一个形如 https://webhook.site/<uuid> 的相匹配的投递 URL。复制那个投递 URL（不带 #!/ 的那个）。让标签页开着；它收到的每个请求都会实时出现在那里。

这个 URL 是你真实 webhook 的替身。把它当作一次性的，因为任何拿到这个 URL 的人都能读到到达的东西。

2. 打开托管验证

在仪表盘里，打开站点密钥，前往它的 托管验证 页。

把 webhook.site 的投递 URL 粘进 webhook URL 字段。
暂时把邮件留空。
保存。

你还不必拨动启用开关。下一步用的是 测试投递，它对一个已保存的目标都能用，不管托管验证有没有打开，于是你可以在上线之前确认接线。

3. 发一次测试投递

在同一页上，用 测试投递。Caputchin 会不跑游戏、不核验令牌就把一次合成提交直接发到你的目标，所以它是对目标接线的一次纯粹检查。

切到 webhook.site 标签页。一两秒内一个新的 POST 出现。它的 JSON 体看起来像这样：

{
  "caputchin": {
    "site_key": "cpt_pub_...",
    "session_id": "test_...",
    "game_id": null,
    "score": null,
    "duration_ms": null,
    "verified_at": 1748640000000,
    "test": true
  },
  "form": {
    "email": "test@example.com",
    "message": "Test submission from your Caputchin dashboard."
  }
}

那个 "test": true 标记告诉你的处理器这是一次仪表盘测试、而非一位真实访客；它在真实提交上不存在。如果你看到这个载荷，目标就能用。如果什么都没到，再检查一下你复制的是投递 URL（不是那个 #!/ 查看器 URL）并保存了它。

4. 把你的表单指向转发器

现在让一次真实提交穿过 Caputchin。对你表单唯一的改动是它的 action：它不再提交到你自己的后端，而是提交到站点密钥在托管验证页上向你显示的那个转发器 URL。

<form action="https://caputchin.com/api/forward/cpt_pub_..." method="POST">
  <input name="email" type="email" />
  <input name="message" />
  <caputchin-widget sitekey="cpt_pub_..."></caputchin-widget>
  <button type="submit">Send</button>
</form>

其他都不变。组件仍在访客通过挑战时注入那个隐藏的 caputchin-token 字段；转发器读那个字段、核验它，并在把其余的投递到你目标之前把它剥离。

5. 启用托管验证

回到托管验证页，把启用开关拨开并保存。转发器会拒绝一个未启用的站点密钥的提交，所以这个开关就是让第 4 步生效的东西。

6. 真正提交一次表单

加载你的页面、填好表单、通过挑战、并提交。盯着 webhook.site 标签页：第二个 POST 到了，这一次没有 test 字段，并带着真实的验证元数据。

{
  "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 核验、你的目标只收到已核验的提交。一次核验失败的提交（一个缺失的、过期的或重用的令牌）根本到不了你的目标。

像对待一个后端裁定那样对待这个 caputchin 块：game_id、score 和 duration_ms 是给你分析用的客户端声称的元数据，不是一个信任信号。信任决定就是这次提交终究到达了这一事实。这三个里的任何一个在真实提交上都可能是 null（例如一次没有游戏的验证），所以在你读它们之前先防 null。

7. 也试试邮件目标

webhook.site 还给每个收件箱一个邮件地址，所以你可以用同样的方式测试邮件投递。在 webhook.site 页面上，找到你收件箱的唯一邮件地址并复制它；在撰写本文时它看起来像 <your-inbox-id>@emailhook.site，但以页面上的为准，因为那个细节归 webhook.site 所有。然后：

回到托管验证页，把那个地址粘进邮件字段。
保存，并再用一次 测试投递。

邮件和那些请求一起到达 webhook.site 收件箱：一封朴素的消息，携带表单字段和一个注明 Caputchin 已核验该提交的页脚。邮件通过 Caputchin 的邮件提供商投递，所以它落地可能比一个 webhook POST 稍慢一点。同时设了一个 webhook URL 和一个邮件地址时，一次提交会扇出到两者，并且只要其中一个成功就算作已投递。

8. 换上你真实的目标

当测试收件箱已经向你展示该期待什么时，把它换成你自己的：

你自己的 webhook。 把你端点的 URL 放进 webhook URL 字段。它必须是一个公开的 https URL；Caputchin 会拒绝那些解析到私有、回环或云元数据地址的 URL，而且它不会跟随重定向。你的处理器会收到恰好就是上面那个 JSON 形状。投递不签名，所以把 URL 保密，因为它的保密性即为这个调用的身份验证。
改用邮件，或一并用。 把你自己的地址放进邮件字段，就像你上面测试它的方式。你可以两个同时跑，例如一个 webhook 做处理加一份邮件副本给自己。

对着这个上线的目标再发一次真实提交来确认，然后你就完成了。

接下来去哪里

托管验证统计：随时间观察投递健康度。
托管验证：这些概念、隐私姿态，以及什么被有意略去。
在你的后端核验：如果你日后加了一台服务器时的那个替代方案。

用一个测试收件箱设置托管验证

本页内容