Référence de la charge du webhook

Quand un envoi réussit la vérification, le relais envoie un POST vers l'URL de webhook que tu as configurée. Cette page est le contrat exact pour cette requête. Pour la marche à suivre de configuration, vois configurer la vérification hébergée ; pour le concept, vois vérifier sans backend.

Ligne de requête et en-têtes

Le relais envoie un POST avec un corps JSON et ces en-têtes :

En-tête	Valeur
`content-type`	`application/json`
`accept`	`application/json`
`user-agent`	`Caputchin-Forwarder/0.1`
`x-caputchin-test`	`1`, présent seulement sur un Tester l'envoi du tableau de bord ; absent sur les envois réels

L'appel est envoyé avec les redirections désactivées et un délai de quelques secondes. La requête n'est pas signée ; c'est le secret de l'URL du webhook qui l'authentifie.

Corps

Le corps est un objet JSON avec deux clés de premier niveau, caputchin (les métadonnées de vérification que Caputchin ajoute) et form (tes champs envoyés) :

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

L'objet `caputchin`

Champ	Type	Signification
`site_key`	string	La clé publique `cpt_pub_...` d'où venait l'envoi.
`session_id`	string	Un id de session de vérification opaque, utile pour la corrélation ou la déduplication. Sur un envoi de test, il est préfixé `test_`.
`game_id`	string ou null	Le jeu que le visiteur a joué. Null quand la vérification a tourné sans jeu.
`score`	number ou null	Le score du jeu. Métadonnée revendiquée par le client pour l'analytique, jamais un signal de confiance. Null quand non applicable.
`duration_ms`	number ou null	Combien de temps le visiteur a passé à jouer le jeu, en millisecondes. Revendiqué par le client, pas un signal de confiance. Null quand non applicable (par exemple une vérification sans jeu).
`verified_at`	number	Quand Caputchin a vérifié le token, en epoch Unix en millisecondes.
`test`	boolean (optionnel)	Présent et `true` seulement sur un envoi de test du tableau de bord. Absent sur les envois réels.

game_id, score et duration_ms sont chacun nullable sur un envoi réel, donc protège-toi contre null avant de les lire. Aucun des champs caputchin n'est une décision de confiance : la confiance est que la requête soit arrivée tout court, parce qu'un envoi qui échoue à la vérification n'est jamais relayé.

L'objet `form`

form est un objet plat de tes champs envoyés sous forme de clés string et de valeurs string, exactement comme posté, avec un changement : le champ caputchin-token est retiré avant la livraison, donc il n'apparaît jamais ici. Le relais accepte seulement les champs texte ; un envoi portant un téléversement de fichier est rejeté avant toute livraison.

Ce que ton handler devrait renvoyer

Renvoie n'importe quel statut 2xx pour accuser réception. Le relais traite une réponse non-2xx, un délai dépassé, ou un échec de connexion comme une livraison échouée, et une livraison échouée n'est pas réessayée. Suis la santé de livraison sur la page statistiques.

Voir aussi

Configurer la vérification hébergée : câble un webhook et déclenche un envoi de test.
Vérifier sans backend : le concept, la posture de confidentialité, et les règles de sûreté des URL.
Statistiques de vérification hébergée : lire le succès et l'échec de livraison.