テスト受信箱でホスト型認証を設定する

このチュートリアルの終わりまでに、送信が 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 が 1、2 秒で現れます。その 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 のタブを見てください。2 つ目の 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 はあなたの分析のためのクライアントが申告するメタデータで、信頼のシグナルではありません。信頼の判断は、送信がそもそも届いたという事実です。その 3 つのどれも本物の送信で null になり得る（たとえばゲームのない検証）ので、読む前に null を防いでください。

7. メールの宛先も試す

webhook.site は各受信箱にメールアドレスも渡すので、同じやり方でメール配信をテストできます。webhook.site のページで、受信箱の一意のメールアドレスを見つけてコピーします。執筆時点では <your-inbox-id>@emailhook.site のように見えますが、その詳細は webhook.site が所有するので、現在の形はページで確認してください。それから：

ホスト型認証ページに戻り、そのアドレスを メール フィールドに貼り付けます。
保存し、もう一度 配信をテスト を使います。

メールは、リクエストと並んで webhook.site の受信箱に届きます。フォームのフィールドと、Caputchin が送信を検証したと記すフッターを運ぶ素のメッセージです。メールは Caputchin のメールプロバイダーを通じて配信されるので、webhook の POST より着地に少し時間がかかることがあります。webhook URL とメールアドレスの両方を設定すると、1 つの送信が両方に展開され、どちらか一方が成功すれば配信済みと数えられます。

8. 本物の宛先に差し替える

テスト受信箱が何を期待すべきか見せたら、あなた自身のものに置き換えます：

あなた自身の webhook。 エンドポイントの URL を webhook URL フィールドに入れます。公開の https URL でなければなりません。Caputchin は、プライベート、ループバック、クラウドメタデータのアドレスに解決される URL を拒み、リダイレクトを追従しません。あなたのハンドラーは上とちょうど同じ JSON の形を受け取ります。配信は署名されないので、URL を秘密に保ってください。その秘匿性が呼び出しを認証するものだからです。
代わりに、または加えてメール。 上でテストしたのと同じやり方で、あなた自身のアドレスを メール フィールドに入れます。両方を一度に走らせられます。たとえば処理のための webhook に、自分宛のメールのコピーを加えてです。

確認のためにライブの宛先に対してもう 1 つ本物の送信を送れば、完了です。

次にどこへ

ホスト型認証の統計：時間に沿って配信の健全性を見守る。
ホスト型認証：概念、プライバシーの姿勢、意図的に省かれているもの。
バックエンドで検証する：後でサーバーを足す場合の選択肢。

テスト受信箱でホスト型認証を設定する

このページの内容