3. Antwort verifizieren
Bevor Ihr Server das Formular verarbeitet, sendet er das Antwort-Token an CaptchaFox und prüft, ob es gültig ist. So halten Sie Bots fern: Sie können Anfragen an Ihren Server senden, ohne das Widget je zu laden.
Verifizierungsanfrage senden
Senden Sie eine POST-Anfrage mit dem Content-Type application/x-www-form-urlencoded an:
https://api.captchafox.com/siteverify| Parameter | Erforderlich | Beschreibung |
|---|---|---|
| secret | Ja | Der Geheimschlüssel Ihrer Seite. |
| response | Ja | Das Antwort-Token aus dem Formularfeld cf-captcha-response. |
| sitekey | Nein | Ihr Seitenschlüssel. Empfohlen. |
| remoteIp | Nein | Die IP-Adresse des Besuchers. Muss mit der IP übereinstimmen, die die Herausforderung gelöst hat. |
Jedes Token kann einmal verifiziert werden und ist 2 Minuten gültig. Sie können diese Dauer im Portal verlängern.
Node.js
Verwenden Sie die Bibliothek @captchafox/node :
npm install @captchafox/nodeimport { verify } from '@captchafox/node';
const result = await verify(process.env.CAPTCHAFOX_SECRET, req.body['cf-captcha-response'], {
sitekey: 'IHR_SITEKEY',
remoteIp: req.ip, // optional
});
if (!result.success) {
// Anfrage ablehnen
}Weitere Bibliotheken finden Sie unter Server-Integrationen.
Antwort
Die API antwortet mit einem JSON-Objekt:
| Feld | Typ | Beschreibung |
|---|---|---|
| success | boolean | Ob das Token gültig ist. Prüfen Sie immer dieses Feld: Auch fehlgeschlagene Verifizierungen liefern den Status 200. |
| challenge_ts | string | ISO-Zeitstempel der Herausforderung (yyyy-MM-dd'T'HH:mm:ssZZ). Nur bei Erfolg enthalten. |
| hostname | string | Hostname der Seite, auf der die Herausforderung gelöst wurde. Optional. |
| error-codes | string[] | Warum die Verifizierung fehlgeschlagen ist. Nur enthalten, wenn success false ist. Siehe Fehlercodes. |
| insights | object | Details über die Verifizierung. Nur in Enterprise-Plänen. |
{
"success": true,
"challenge_ts": "2026-11-20T10:15:30+00:00",
"hostname": "example.com"
}Fehlercodes
| Fehlercode | Beschreibung |
|---|---|
| missing-input-secret | Der Geheimschlüssel fehlt. |
| invalid-input-secret | Der Geheimschlüssel ist ungültig oder falsch formatiert. |
| missing-input-response | Das Antwort-Token fehlt. |
| invalid-input-response | Das Antwort-Token ist ungültig oder fehlerhaft. |
| bad-request | Die Anfrage ist ungültig oder fehlerhaft formuliert. |
| timeout-or-duplicate | Das Token ist abgelaufen oder wurde bereits verifiziert. |
| invalid-ip-match | Die IP-Adresse stimmt nicht mit dem Parameter remoteIp überein. |
Häufige Ursachen für fehlgeschlagene Verifizierungen
- Doppelt verifiziert: Tokens können nur einmal verwendet werden. Muss der Nutzer das Formular erneut absenden, rufen Sie
captchafox.reset()auf, um ein neues Token zu erhalten. - Abgelaufen: Der Nutzer hat zu lange mit dem Absenden gewartet.
- Schlüssel passen nicht zusammen: Seitenschlüssel und Geheimschlüssel müssen zur selben Seite gehören.
- Falsche IP: Hinter einem Proxy muss
remoteIpdie IP des Besuchers sein. Im Zweifel lassen Sie den Parameter weg.
Umgang mit Ausfällen
Setzen Sie ein Timeout von wenigen Sekunden für die Anfrage. Ist CaptchaFox nicht erreichbar (Netzwerkfehler, Timeout oder 5xx-Status), können Sie die Anfrage durchlassen, damit Ihr Formular nutzbar bleibt, und den Fall protokollieren.
Tun Sie das niemals, wenn die API mit success: false oder einem 4xx-Status antwortet.
Checkliste vor Livegang
- Die Testschlüssel sind durch Ihre echten Schlüssel ersetzt.
- Jede geschützte Anfrage wird auf dem Server verifiziert und abgelehnt, wenn die Verifizierung fehlschlägt.
- Der Geheimschlüssel ist nur auf Ihrem Server gespeichert.
- Ihre Content Security Policy erlaubt CaptchaFox, falls Sie eine verwenden.
- Wenn Sie den versteckten Modus verwenden, ist der Datenschutzhinweis auf der Seite.