---
type: how-to
title: Von hCaptcha migrieren
summary: "Tausch hCaptcha gegen Caputchin mit minimalen Änderungen: dieselbe Client-Widget-plus-Server-Verifizierung-Form bildet fast eins zu eins ab, hier ist das genaue Vorher-und-Nachher für jedes Stück."
---

Caputchin nutzt dasselbe zweiteilige Modell wie hCaptcha, ein Widget auf der Seite, das ein Token produziert, und eine serverseitige Prüfung, die es bestätigt, also ist das Migrieren meist ein mechanischer Tausch, kein Neuschreiben. Der Server-Austausch spiegelt insbesondere die `siteverify`-Form, der hCaptcha selbst folgt. Diese Anleitung gibt das Vorher-und-Nachher für jedes Stück.

Hast du noch kein Caputchin-Konto und keinen Site-Key erstellt, mach zuerst [dein Konto erstellen](/docs/getting-started/create-your-account); du brauchst einen **Public Key** (`cpt_pub_...`) für die Seite und ein **Secret** (`cpt_sec_...`) für dein Backend, dieselbe Aufteilung wie hCaptchas Site-Key und Secret-Key.

## Das mentale Modell ist unverändert

```mermaid
flowchart LR
  A["Widget auf deiner Seite"] -->|Token| B["Dein Formular / Anfrage"]
  B -->|Token| C["Dein Backend"]
  C -->|Secret + Token| D["siteverify-Endpunkt"]
  D -->|Erfolg?| C
```

Alles, was du schon um hCaptcha gebaut hast, ein Widget rendern, ein Token sammeln, es an deinen Server POSTen, es verifizieren, bevor du der Anfrage traust, bleibt. Nur die Namen und Endpunkte ändern sich.

## 1. Den Client-Snippet tauschen

| | hCaptcha | Caputchin |
|---|---|---|
| Skript | `<script src="https://js.hcaptcha.com/1/api.js" async defer>` | `<script src="https://cdn.jsdelivr.net/npm/@caputchin/widget@3/dist/widget.js">` |
| Element | `<div class="h-captcha" data-sitekey="...">` | `<caputchin-widget sitekey="cpt_pub_...">` |
| Token-Feld in einem Formular | `h-captcha-response` (auto-eingefügt) | `caputchin-token` (auto-eingefügt) |
| Das Token in JS lesen | `hcaptcha.getResponse()` | das [`pass`-Event](/docs/references/widget-methods-and-events) `detail.token` |

Wie hCaptcha **fügt das Caputchin-Widget ein verstecktes Token-Feld automatisch ein** in das Formular, in dem es sitzt, sodass du, wenn dein Formular schon einen normalen POST machte, nur das Element und den Feldnamen änderst, den dein Backend liest. Sieh dir [das Widget hinzufügen](/docs/getting-started/add-the-widget) für die vollständige Client-Einrichtung und [die CDN-vs-npm-Wahl](/docs/integration-guides/cdn) an.

## 2. Die Server-Verifizierung tauschen

Hier sind die zwei am nächsten, die Anfrage- und Antwortformen reihen sich fast Feld für Feld auf.

| | hCaptcha | Caputchin |
|---|---|---|
| Endpunkt | `POST https://api.hcaptcha.com/siteverify` | `POST https://verify.caputchin.com/v1/siteverify` |
| Anfragefelder | `secret`, `response` | `secret`, `response` (identisch) |
| Antwort | `{ success, challenge_ts, hostname, "error-codes", score? }` | `{ success, challenge_ts, hostname, error-codes, score? }` |
| Vertrauensregel | nur handeln, wenn `success === true` | nur handeln, wenn `success === true` (identisch) |

Ein Format-Hinweis: hCaptchas Verifizierungs-Endpunkt erwartet `application/x-www-form-urlencoded`, während Caputchins JSON akzeptiert. Sendete dein bestehender Code form-kodierte Felder, wechsel den Body auf JSON (`{"secret":"...","response":"..."}`) mit `Content-Type: application/json`. Die Felder selbst sind unverändert. Die vollständige Anfrage-/Antwort-Referenz ist auf [ein Token auf deinem Backend verifizieren](/docs/integration-guides/verify-on-your-backend); Framework-Snippets sind in [Backend-Beispielen](/docs/integration-guides/backend-examples).

## 3. Den Score fallen lassen, falls du hCaptcha Enterprise genutzt hast

hCaptcha Enterprise gibt einen Risiko-`score` zurück (wo eine **höhere** Zahl **mehr** Risiko bedeutet) und bittet dich, eine Schwelle zu wählen. Caputchin funktioniert **nicht** so: `success` ist ein maßgebliches Bestanden/Nicht, weil die Verifizierung tatsächlich gelöst wurde (eine Proof-of-Work-Prüfung oder eine [auf dem Server neu abgeleitete Spiel-Runde](/docs/understanding-caputchin/gaming-anti-cheat)), keine Risiko-Schätzung.

Hatte dein Code `if (data.score < 0.7)`, ersetz ihn durch `if (data.success)`. Caputchins `score`-Feld ist unverwandt: es existiert nur für Spiel-Runden und ist die Punktzahl des **Spiels** (informativ, für deine eigenen Bestenlisten), nie ein Risiko oder eine Bot-Wahrscheinlichkeit, also gate Zugriff nicht daran. (Beachte, die Richtung ist auch entgegengesetzt, hCaptchas Score steigt mit dem Risiko; Caputchins steigt mit der Spiel-Leistung.)

## Was übernommen wird und was sich verbessert

- **Die Datenschutz-Haltung, für die du hCaptcha gewählt hast, bleibt.** Caputchin erfasst keine IP, keinen User-Agent, keinen Fingerabdruck und keine Verhaltens-Telemetrie; das Protokoll hat nirgendwo, einen Besucher-Identifier abzulegen, also gibt es keinen zu leaken oder zu verkaufen. Sieh dir die [Philosophie](/docs/understanding-caputchin/philosophy) an.
- **Ein optionales Spiel.** Statt einer Bild-Auswahl-Aufgabe kannst du die Verifizierung in ein kurzes Spiel verwandeln, das deine Besucher tatsächlich spielen, und es ist der Teil, der gegen KI-Löser standhält. Sieh dir [ein Spiel hinzufügen](/docs/getting-started/add-a-game) an.
- **Eine strikte CSP bleibt strikt.** Caputchin läuft unter einer engen Content-Security-Policy; du erlaubst ein paar Origins, statt deine Policy zu lockern. Sieh dir [wie Caputchin Spiele sandboxt](/docs/understanding-caputchin/game-sandboxing#the-csp-you-set-on-your-own-page) an.

## Stolperfallen

- **Zwei Keys, zwei Heimaten.** Der Public Key (`cpt_pub_...`) kommt auf die Seite; das Secret (`cpt_sec_...`) bleibt nur serverseitig, genau die hCaptcha-Disziplin. Liefer das Secret nicht an den Browser.
- **Das Token ist einmalig.** Wie hCaptcha verifiziert ein Token einmal. Cache oder spiel es nicht ab.
- **Änder den Feldnamen, den dein Backend liest.** Das versteckte Feld ist `caputchin-token`, nicht `h-captcha-response`, ein häufiger Ein-Zeilen-Fehler.
- **Body-Format.** Sende die Verifizierungs-Anfrage als JSON, nicht form-kodiert.

## Siehe auch

- [Das Widget hinzufügen](/docs/getting-started/add-the-widget): die vollständige Client-Einrichtung.
- [Ein Token auf deinem Backend verifizieren](/docs/integration-guides/verify-on-your-backend): die maßgebliche `siteverify`-Referenz.
- [Backend-Beispiele](/docs/integration-guides/backend-examples): der Verifizierungs-Aufruf in jeder Sprache.
- [Ein Spiel hinzufügen](/docs/getting-started/add-a-game): die Verifizierung in ein Spiel verwandeln.