---
type: reference
title: Référence de la charge du webhook
summary: La requête exacte qu'un webhook de vérification hébergée reçoit, chaque champ du corps, et les en-têtes que Caputchin envoie.
---

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](/docs/hosted-verification/set-up) ; pour le concept, vois [vérifier sans backend](/docs/hosted-verification/overview).

## 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) :

```json
{
  "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](/docs/hosted-verification/statistics).

## Voir aussi

- [Configurer la vérification hébergée](/docs/hosted-verification/set-up) : câble un webhook et déclenche un envoi de test.
- [Vérifier sans backend](/docs/hosted-verification/overview) : le concept, la posture de confidentialité, et les règles de sûreté des URL.
- [Statistiques de vérification hébergée](/docs/hosted-verification/statistics) : lire le succès et l'échec de livraison.