---
type: reference
title: Webhook-Payload-Referenz
summary: Die genaue Anfrage, die ein Webhook der gehosteten Verifizierung empfängt, jedes Feld im Body und die Header, die Caputchin sendet.
---

Wenn eine Einsendung die Verifizierung besteht, sendet die Weiterleitung einen `POST` an deine konfigurierte Webhook-URL. Diese Seite ist der genaue Vertrag für diese Anfrage. Für die Setup-Anleitung sieh dir [gehostete Verifizierung einrichten](/docs/hosted-verification/set-up) an; für das Konzept sieh dir [ohne Backend verifizieren](/docs/hosted-verification/overview) an.

## Anfragezeile und Header

Die Weiterleitung sendet einen `POST` mit einem JSON-Body und diesen Headern:

| Header | Wert |
|---|---|
| `content-type` | `application/json` |
| `accept` | `application/json` |
| `user-agent` | `Caputchin-Forwarder/0.1` |
| `x-caputchin-test` | `1`, nur bei einer Dashboard-**Testzustellung** vorhanden; fehlt bei echten Einsendungen |

Der Aufruf wird mit deaktivierten Redirects und einem Timeout von ein paar Sekunden gesendet. Die Anfrage ist nicht signiert; die Geheimhaltung der Webhook-URL ist es, was sie authentifiziert.

## Body

Der Body ist ein JSON-Objekt mit zwei Schlüsseln auf oberster Ebene, `caputchin` (Verifizierungs-Metadaten, die Caputchin hinzufügt) und `form` (deine eingesendeten Felder):

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

### Das `caputchin`-Objekt

| Feld | Typ | Bedeutung |
|---|---|---|
| `site_key` | string | Der öffentliche `cpt_pub_...`-Key, von dem die Einsendung kam. |
| `session_id` | string | Eine opake Verifizierungs-Session-id, nützlich zur Korrelation oder Deduplizierung. Bei einer Testzustellung ist sie mit `test_` präfixiert. |
| `game_id` | string oder null | Das Spiel, das der Besucher gespielt hat. Null, wenn die Verifizierung ohne Spiel lief. |
| `score` | number oder null | Die Spiel-Punktzahl. Vom Client behauptete Metadaten für Analysen, nie ein Vertrauenssignal. Null, wenn nicht anwendbar. |
| `duration_ms` | number oder null | Wie lange der Besucher mit dem Spiel verbracht hat, in Millisekunden. Vom Client behauptet, kein Vertrauenssignal. Null, wenn nicht anwendbar (zum Beispiel eine Verifizierung ohne Spiel). |
| `verified_at` | number | Wann Caputchin das Token verifizierte, als Unix-Epoche in Millisekunden. |
| `test` | boolean (optional) | Nur bei einer Dashboard-Testzustellung vorhanden und `true`. Fehlt bei echten Einsendungen. |

`game_id`, `score` und `duration_ms` sind bei einer echten Einsendung jeweils nullable, also guard auf null, bevor du sie liest. Keines der `caputchin`-Felder ist eine Vertrauensentscheidung: das Vertrauen ist, dass die Anfrage überhaupt ankam, weil eine Einsendung, die die Verifizierung nicht besteht, nie weitergeleitet wird.

### Das `form`-Objekt

`form` ist ein flaches Objekt deiner eingesendeten Felder als String-Schlüssel und String-Werte, genau wie gepostet, mit einer Änderung: das `caputchin-token`-Feld wird vor der Zustellung entfernt, sodass es hier nie erscheint. Die Weiterleitung akzeptiert nur Textfelder; eine Einsendung, die einen Datei-Upload trägt, wird vor jeder Zustellung abgelehnt.

## Was dein Handler zurückgeben sollte

Gib einen beliebigen `2xx`-Status zurück, um den Empfang zu bestätigen. Die Weiterleitung behandelt eine Nicht-`2xx`-Antwort, ein Timeout oder einen Verbindungsfehler als fehlgeschlagene Zustellung, und eine fehlgeschlagene Zustellung wird nicht wiederholt. Verfolge die Zustellungsgesundheit auf der [Statistik](/docs/hosted-verification/statistics)-Seite.

## Siehe auch

- [Gehostete Verifizierung einrichten](/docs/hosted-verification/set-up): einen Webhook verdrahten und eine Testzustellung feuern.
- [Ohne Backend verifizieren](/docs/hosted-verification/overview): das Konzept, die Datenschutz-Haltung und die URL-Sicherheitsregeln.
- [Statistik der gehosteten Verifizierung](/docs/hosted-verification/statistics): Zustellungserfolg und -fehlschlag lesen.