Gehostete Verifizierung mit einem Test-Posteingang einrichten

Am Ende dieses Tutorials hast du ein funktionierendes Kontaktformular, dessen Einsendungen von Caputchin verifiziert und an einen Webhook zugestellt werden, und du hast eine verifizierte Einsendung in einem Test-Posteingang landen sehen, den du inspizieren kannst. Wir nutzen zuerst webhook.site als Ziel, weil es dir die genaue Payload zeigt, die Caputchin sendet, bevor du dich auf deinen eigenen Endpunkt festlegst.

Du brauchst einen Alpha-, Troop- oder Apex-Tarif (gehostete Verifizierung ist nicht auf Solo), einen Site-Key und eine Seite, auf der du das HTML des Formulars bearbeiten kannst. Hast du das Widget noch nicht zu einer Seite hinzugefügt, mach zuerst das Widget hinzufügen; dieses Tutorial setzt ein funktionierendes <caputchin-widget> voraus.

1. Einen Test-Posteingang holen

Öffne webhook.site in einem neuen Tab. Es gibt dir sofort eine eindeutige URL, die wie https://webhook.site/#!/<uuid> aussieht, und eine passende Zustell-URL der Form https://webhook.site/<uuid>. Kopier die Zustell-URL (die ohne das #!/). Lass den Tab offen; jede Anfrage, die er empfängt, erscheint dort in Echtzeit.

Diese URL ist ein Platzhalter für deinen echten Webhook. Behandle sie als Wegwerf, da jeder mit der URL lesen kann, was ankommt.

2. Gehostete Verifizierung einschalten

Öffne im Dashboard den Site-Key und geh auf seine Gehostete Verifizierung-Seite.

1. Füg die webhook.site-Zustell-URL in das Feld Webhook-URL ein.
2. Lass E-Mail vorerst leer.
3. Speichern.

Du musst den Aktiviert-Schalter noch nicht umlegen. Der nächste Schritt nutzt Testzustellung, die auf einem gespeicherten Ziel funktioniert, ob gehostete Verifizierung eingeschaltet ist oder nicht, sodass du die Verdrahtung bestätigen kannst, bevor du live gehst.

3. Eine Testzustellung senden

Nutz auf derselben Seite Testzustellung. Caputchin sendet eine synthetische Einsendung direkt an dein Ziel, ohne ein Spiel auszuführen oder ein Token zu verifizieren, also ist es eine reine Prüfung der Ziel-Verdrahtung.

Wechsel zum webhook.site-Tab. Ein neuer POST erscheint innerhalb von ein, zwei Sekunden. Sein JSON-Body sieht so aus:

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

Der "test": true-Marker sagt deinem Handler, dass dies ein Dashboard-Test war, kein echter Besucher; er fehlt bei echten Einsendungen. Siehst du diese Payload, funktioniert das Ziel. Kommt nichts an, prüf noch einmal, dass du die Zustell-URL kopiert hast (nicht die #!/-Viewer-URL) und sie gespeichert hast.

4. Dein Formular auf die Weiterleitung richten

Jetzt lass eine echte Einsendung durch Caputchin laufen. Die einzige Änderung an deinem Formular ist sein action: statt deines eigenen Backends postet es an die Weiterleitungs-URL, die der Site-Key dir auf der Gehostete-Verifizierung-Seite zeigt.

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

Sonst ändert sich nichts. Das Widget fügt weiterhin das versteckte caputchin-token-Feld ein, wenn der Besucher die Aufgabe löst; die Weiterleitung liest dieses Feld, verifiziert es und entfernt es, bevor sie den Rest an dein Ziel zustellt.

5. Gehostete Verifizierung aktivieren

Zurück auf der Gehostete-Verifizierung-Seite leg den Aktiviert-Schalter um und speichere. Die Weiterleitung lehnt Einsendungen für einen Site-Key ab, der nicht aktiviert ist, also ist dieser Schalter das, was Schritt 4 live macht.

6. Das Formular wirklich absenden

Lad deine Seite, füll das Formular, lös die Aufgabe und sende ab. Beobachte den webhook.site-Tab: ein zweiter POST kommt an, diesmal ohne test-Feld und mit echten Verifizierungs-Metadaten.

{
  "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 ist der ganze Pfad: Besucher sendet ab, Caputchin verifiziert, dein Ziel empfängt nur die verifizierte Einsendung. Eine Einsendung, die die Verifizierung nicht besteht (ein fehlendes, abgelaufenes oder wiederverwendetes Token), erreicht dein Ziel gar nicht erst.

Behandle den caputchin-Block so, wie du ein Backend-Urteil behandeln würdest: game_id, score und duration_ms sind vom Client behauptete Metadaten für deine Analysen, kein Vertrauenssignal. Die Vertrauensentscheidung ist die Tatsache, dass die Einsendung überhaupt ankam. Jedes dieser drei kann bei einer echten Einsendung null sein (zum Beispiel eine Verifizierung ohne Spiel), also guard auf null, bevor du sie liest.

7. Auch das E-Mail-Ziel ausprobieren

webhook.site gibt jedem Posteingang auch eine E-Mail-Adresse, sodass du die E-Mail-Zustellung auf dieselbe Weise testen kannst. Find auf der webhook.site-Seite die eindeutige E-Mail-Adresse deines Posteingangs und kopier sie; zum Zeitpunkt des Schreibens sieht sie wie <your-inbox-id>@emailhook.site aus, aber prüf die Seite auf die aktuelle Form, da webhook.site dieses Detail besitzt. Dann:

1. Zurück auf der Gehostete-Verifizierung-Seite, füg diese Adresse in das Feld E-Mail ein.
2. Speichere und nutz Testzustellung erneut.

Die E-Mail kommt im webhook.site-Posteingang neben den Anfragen an: eine schlichte Nachricht, die die Formularfelder trägt, und eine Fußzeile, die vermerkt, dass Caputchin die Einsendung verifiziert hat. E-Mail wird über Caputchins E-Mail-Provider zugestellt, also kann sie etwas länger brauchen als ein Webhook-POST. Mit sowohl einer Webhook-URL als auch einer E-Mail-Adresse gesetzt fächert eine einzelne Einsendung zu beiden aus und zählt als zugestellt, wenn eines von beiden gelingt.

8. Dein echtes Ziel einsetzen

Wenn der Test-Posteingang dir gezeigt hat, was zu erwarten ist, ersetz ihn durch dein eigenes:

• Dein eigener Webhook. Setz die URL deines Endpunkts in das Feld Webhook-URL. Es muss eine öffentliche https-URL sein; Caputchin weist URLs ab, die zu privaten, Loopback- oder Cloud-Metadaten-Adressen auflösen, und es folgt keinen Redirects. Dein Handler empfängt genau die JSON-Form oben. Zustellungen sind nicht signiert, also halt die URL geheim, da ihre Geheimhaltung den Aufruf authentifiziert.
• E-Mail stattdessen, oder zusätzlich. Setz deine eigene Adresse in das Feld E-Mail, genauso, wie du es oben getestet hast. Du kannst beide gleichzeitig betreiben, zum Beispiel einen Webhook zur Verarbeitung plus eine E-Mail-Kopie an dich selbst.

Sende eine weitere echte Einsendung gegen das Live-Ziel zur Bestätigung, dann bist du fertig.

Wohin als Nächstes

• Statistik der gehosteten Verifizierung: die Zustellungsgesundheit über die Zeit beobachten.
• Gehostete Verifizierung: die Konzepte, die Datenschutz-Haltung und was bewusst weggelassen ist.
• Auf deinem Backend verifizieren: die Alternative, falls du später einen Server hinzufügst.