TrustComponent
Fastify
TrustCaptcha · Bot-Schutz

Fastify CAPTCHA-Integration

Mit wenigen Zeilen TypeScript richtest du ein Fastify-CAPTCHA in einer Route oder einem preHandler-Hook ein. TrustCaptcha stoppt Bot-Spam in Logins, Registrierungen und Kontaktformularen, und deine Schema-Validierung und das formbody-Plugin funktionieren weiter. EU-gehostet, DSGVO-konform und ohne Bilderrätsel.

Schnellstart

So funktioniert die Integration

1. CAPTCHA erstellen

Erstelle ein Benutzerkonto oder melde dich mit einem bestehenden Konto an. Dann erstellst du ein neues CAPTCHA oder wählst ein vorhandenes aus. Wenn du TrustCaptcha erst ausprobieren willst: Jeder Tarif startet mit einer 14-tägigen kostenlosen Testphase.

Auf der Übersichtsseite des CAPTCHAs findest du den Site Key und den License Key, und dort erstellst du auch deinen API-Key. Trage die Domains deiner Website in den Sicherheitsregeln des CAPTCHAs als autorisierte Domains ein, damit sie dein CAPTCHA nutzen dürfen.

Start des Formulars zur Erstellung eines CAPTCHA.
CAPTCHA-Sicherheitsregeln eines Demo-CAPTCHAs.

2. CAPTCHA-Widget in dein Formular einbauen

Binde das TrustCaptcha-Widget in das HTML-Formular ein, das deine Fastify-Route ausliefert. Das Widget läuft im Hintergrund und fügt beim Absenden ein verstecktes Feld tc-verification-token hinzu, das auf request.body ankommt wie jeder andere Input.

contact.html
HTML
<script type="module" src="https://cdn.trustcomponent.com/trustcaptcha/3.0.x/trustcaptcha.esm.min.js"></script>

<form method="post" action="/contact">
    <input type="email" name="email" required>
    <trustcaptcha-component sitekey="<your_site_key>"></trustcaptcha-component>
    <button type="submit">Send</button>
</form>

Das CAPTCHA-Widget wird anschließend in deinem Formular angezeigt:

CAPTCHA-Widget vor dem Start

Detaillierte Informationen zur CAPTCHA-Widget-Integration?
Die vollständige Widget-Referenz mit Themes, Sprachen, eigenem Design und mehr findest du in unserer Dokumentation.

Dokumentation lesen

3. Token in deiner Fastify-Route validieren

Hole in deinem Fastify-Route-Handler den Verifikationstoken aus request.body, rufe das Ergebnis über unsere Node.js-Library ab und entscheide, ob die Anfrage akzeptiert werden soll.

Installiere zunächst unsere TrustCaptcha-Node.js-Library zusammen mit Fastifys formbody-Plugin:

Install
bash
npm i fastify @fastify/formbody @trustcomponent/trustcaptcha-nodejs

Validiere dann den Token in deiner Fastify-Route und reagiere auf das Ergebnis:

server.ts
TypeScript
import Fastify from "fastify";
import formbody from "@fastify/formbody";
import { TrustCaptcha } from "@trustcomponent/trustcaptcha-nodejs";

const fastify = Fastify();
await fastify.register(formbody);

fastify.post("/contact", async (request, reply) => {
  const body = request.body as Record<string, string>;
  const token = body["tc-verification-token"] ?? "";

  try {
    const result = await TrustCaptcha.getVerificationResult("<your_api_key>", token);
    if (!result.verificationPassed || result.score > 0.5) {
      return reply.code(400).send("CAPTCHA verification failed.");
    }
  } catch {
    return reply.code(400).send("CAPTCHA verification failed.");
  }

  // CAPTCHA bestanden — Anfrage verarbeiten
  return reply.send("Thanks!");
});

Detaillierte Informationen zur Fastify-CAPTCHA-Integration?
Die vollständige Schritt-für-Schritt-Anleitung, inklusive eines wiederverwendbaren preHandler-Hooks für Projekte mit mehreren geschützten Routen, findest du in unserer Dokumentation.

Dokumentation lesen

Anderes Backend-Framework statt Fastify?
Wenn du ein anderes Framework nutzt, wähle hier das passende Rezept aus. Ist dein Framework nicht aufgeführt, können deine Softwareentwickler die Verifizierung mithilfe unserer Dokumentation selbst integrieren oder unser Support-Team nach einer vorgefertigten Integration fragen.

Actix Web
ASP.NET Core
Axum
Django
Echo
Express
FastAPI
Fastify
Fiber
Flask
Gin
Hapi
Laravel
Micronaut
NestJS
Next.js
Quarkus
Ruby on Rails
Sinatra
Spring Boot
Symfony

4. Integration testen

TrustCaptcha ist jetzt aktiv. Schick eine Testanfrage ab und prüfe, ob sie durchgeht.

CAPTCHA abgeschlossen

Häufige Fragen

Wo gehört die Prüfung des Fastify-CAPTCHAs hin?
Im Route-Handler, der das Formular-Submit empfängt, oder bei mehreren geschützten Routen in einem preHandler-Hook (Fastifys Pendant zu Per-Route-Middleware). Der CAPTCHA-Token kommt auf request.body unter dem Standardnamen "tc-verification-token" an.
Brauche ich ein spezielles Plugin, um Form-Submits zu empfangen?
Ja. Fastify parst JSON automatisch, aber für application/x-www-form-urlencoded (das übliche HTML-Form-Submit) registrierst du das Plugin @fastify/formbody. Ohne dieses Plugin ist request.body bei Form-Submits undefiniert, und die CAPTCHA-Verifizierung hat dann nichts zu lesen.
Wie teile ich API-Key und SDK über die Routen hinweg?
Baue eine einzige TrustCaptcha-Instanz beim Start, hänge sie über fastify.decorate("trustCaptcha", instance) an und lies sie in jeder Route oder jedem Hook über request.server.trustCaptcha. So vermeidest du, das SDK pro Request neu aufzubauen.
Entfernt Fastifys JSON-Schema-Validierung den CAPTCHA-Token?
Möglicherweise. Wenn du ein striktes Body-Schema für die Route deklariert hast, ergänze tc-verification-token darin (oder setze additionalProperties: true), damit der Token nicht entfernt wird, bevor Hook oder Handler ihn lesen.
Kann ich den CAPTCHA-Hook auf eine Route-Gruppe begrenzen?
Ja. Registriere den preHandler in einem fastify.register(...)-Plugin, das auf einen Routen-Prefix begrenzt ist (z.B. /forms). So läuft die Verifizierung automatisch für jede Route unter diesem Prefix.
Leads verlieren wegen CAPTCHAs?

TrustCaptcha blockiert Spam und Bots, nicht deine Kunden. Keine Rätsel, DSGVO-konform, in der EU gehostet.

CAPTCHA-Start
CAPTCHA abgeschlossen
Keine Rätsel für Besucher
Die Prüfung läuft im Hintergrund, während Besucher tippen. So schicken mehr Menschen deine Formulare ab, statt vorher aufzugeben.
DSGVO-konform
In der EU gehostet, ohne Cookies, mit verschlüsselter Übertragung und automatischer Löschung. Jeder Kunde bekommt einen Auftragsverarbeitungsvertrag (AVV).
Mehrstufige Sicherheit
Adaptiver Proof-of-Work und Risiko-Scoring stoppen Missbrauch früh, auch wenn der Angriffs-Traffic plötzlich steigt.
Volle Kontrolle
Stell die Empfindlichkeit ein, pflege Allow- und Blocklisten und nutze Geoblocking. Du entscheidest, wie streng die Prüfung ist.

Schütze deine Fastify-Anwendung in wenigen Schritten mit TrustCaptcha!

  • EU-hosted & DSGVO-konform
  • Keine Rätsel
  • 14 Tage kostenlos testen