Webhook-Payload-Referenz

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 an; für das Konzept sieh dir ohne Backend verifizieren 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):

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

Siehe auch

Gehostete Verifizierung einrichten: einen Webhook verdrahten und eine Testzustellung feuern.
Ohne Backend verifizieren: das Konzept, die Datenschutz-Haltung und die URL-Sicherheitsregeln.
Statistik der gehosteten Verifizierung: Zustellungserfolg und -fehlschlag lesen.