Configurer la vérification hébergée avec une boîte de test

À la fin de ce tutoriel, tu auras un formulaire de contact fonctionnel dont les envois sont vérifiés par Caputchin et livrés à un webhook, et tu auras vu un envoi vérifié atterrir dans une boîte de test que tu peux inspecter. On utilise d'abord webhook.site comme destination, parce qu'il te montre la charge exacte que Caputchin envoie avant que tu ne t'engages sur ton propre point de terminaison.

Il te faut une offre Alpha, Troop ou Apex (la vérification hébergée n'est pas sur Solo), une clé de site, et une page où tu peux éditer le HTML du formulaire. Si tu n'as pas encore ajouté le widget à une page, fais d'abord ajouter le widget ; ce tutoriel suppose un <caputchin-widget> fonctionnel.

1. Obtiens une boîte de test

Ouvre webhook.site dans un nouvel onglet. Il te donne immédiatement une URL unique qui ressemble à https://webhook.site/#!/<uuid>, et une URL de livraison correspondante de la forme https://webhook.site/<uuid>. Copie l'URL de livraison (celle sans le #!/). Laisse l'onglet ouvert ; chaque requête qu'il reçoit y apparaît en temps réel.

Cette URL est un substitut de ton vrai webhook. Traite-la comme jetable, puisque quiconque a l'URL peut lire ce qui arrive.

2. Active la vérification hébergée

Dans le tableau de bord, ouvre la clé de site et va sur sa page Vérification hébergée.

1. Colle l'URL de livraison webhook.site dans le champ URL du webhook.
2. Laisse e-mail vide pour l'instant.
3. Enregistre.

Tu n'as pas encore à basculer l'interrupteur activée. L'étape suivante utilise Tester l'envoi, qui fonctionne sur une destination enregistrée, que la vérification hébergée soit activée ou non, donc tu peux confirmer le câblage avant la mise en ligne.

3. Envoie un envoi de test

Sur la même page, utilise Tester l'envoi. Caputchin envoie un envoi synthétique directement vers ta destination sans exécuter de jeu ni vérifier de token, donc c'est une pure vérification du câblage de la destination.

Bascule vers l'onglet webhook.site. Un nouveau POST apparaît en une seconde ou deux. Son corps JSON ressemble à ceci :

{
  "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."
  }
}

Le marqueur "test": true indique à ton handler que c'était un test du tableau de bord, pas un vrai visiteur ; il est absent sur les envois réels. Si tu vois cette charge, la destination fonctionne. Si rien n'arrive, revérifie que tu as copié l'URL de livraison (pas l'URL de visualisation #!/) et que tu l'as enregistrée.

4. Pointe ton formulaire vers le relais

Maintenant, fais qu'un vrai envoi passe par Caputchin. Le seul changement à ton formulaire est son action : au lieu de ton propre backend, il poste vers l'URL du relais que la clé de site te montre sur la page Vérification hébergée.

<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>

Rien d'autre ne change. Le widget injecte toujours le champ caché caputchin-token quand le visiteur réussit l'épreuve ; le relais lit ce champ, le vérifie, et le retire avant de livrer le reste à ta destination.

5. Active la vérification hébergée

De retour sur la page Vérification hébergée, bascule l'interrupteur activée et enregistre. Le relais rejette les envois pour une clé de site qui n'est pas activée, donc cet interrupteur est ce qui rend l'étape 4 active.

6. Envoie le formulaire pour de vrai

Charge ta page, remplis le formulaire, réussis l'épreuve, et envoie. Surveille l'onglet webhook.site : un second POST arrive, cette fois sans champ test et avec de vraies métadonnées de vérification.

{
  "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!"
  }
}

C'est tout le chemin : le visiteur envoie, Caputchin vérifie, ta destination ne reçoit que l'envoi vérifié. Un envoi qui échoue à la vérification (un token manquant, expiré ou réutilisé) n'atteint jamais ta destination du tout.

Traite le bloc caputchin comme tu traiterais un verdict de backend : game_id, score et duration_ms sont des métadonnées revendiquées par le client pour ton analytique, pas un signal de confiance. La décision de confiance est le fait que l'envoi soit arrivé tout court. N'importe lequel de ces trois peut être null sur un envoi réel (par exemple une vérification sans jeu), donc protège-toi contre null avant de les lire.

7. Essaie aussi la destination e-mail

webhook.site donne aussi à chaque boîte une adresse e-mail, donc tu peux tester la livraison e-mail de la même façon. Sur la page webhook.site, trouve l'adresse e-mail unique de ta boîte et copie-la ; au moment d'écrire elle ressemble à <your-inbox-id>@emailhook.site, mais vérifie la page pour la forme actuelle puisque webhook.site possède ce détail. Puis :

1. De retour sur la page Vérification hébergée, colle cette adresse dans le champ e-mail.
2. Enregistre, et utilise Tester l'envoi de nouveau.

L'e-mail arrive dans la boîte webhook.site aux côtés des requêtes : un message simple portant les champs du formulaire et un pied de page notant que Caputchin a vérifié l'envoi. L'e-mail est livré via le fournisseur d'e-mail de Caputchin, donc il peut mettre un peu plus de temps à atterrir qu'un POST de webhook. Avec à la fois une URL de webhook et une adresse e-mail réglées, un seul envoi se diffuse vers les deux, et compte comme livré si l'un ou l'autre réussit.

8. Bascule vers ta vraie destination

Quand la boîte de test t'a montré ce à quoi t'attendre, remplace-la par la tienne :

• Ton propre webhook. Mets l'URL de ton point de terminaison dans le champ URL du webhook. Ce doit être une URL https publique ; Caputchin refuse les URL qui se résolvent en adresses privées, de bouclage ou de métadonnées cloud, et il ne suivra pas les redirections. Ton handler reçoit exactement la forme JSON ci-dessus. Les livraisons ne sont pas signées, donc garde l'URL secrète, puisque c'est son secret qui authentifie l'appel.
• E-mail à la place, ou en plus. Mets ta propre adresse dans le champ e-mail, de la même façon que tu l'as testé ci-dessus. Tu peux exécuter les deux à la fois, par exemple un webhook pour le traitement plus une copie e-mail pour toi.

Envoie un dernier envoi réel contre la destination en ligne pour confirmer, et tu as fini.

Où aller ensuite

• Statistiques de vérification hébergée : surveille la santé de livraison dans le temps.
• Vérification hébergée : les concepts, la posture de confidentialité, et ce qui est laissé de côté intentionnellement.
• Vérifier sur ton backend : l'alternative si tu ajoutes un serveur plus tard.