TrustCaptcha – Bot protection

Fastify CAPTCHA Integration

Wire TrustCaptcha into a Fastify route or preHandler hook in just a few lines of TypeScript. Stop bot-driven spam on logins, signups and contact forms — without breaking your schema validation or formbody plugin. EU-hosted, GDPR-ready, no image puzzles.

Quickstart

How the integration works

1. Create a CAPTCHA

Create a user account or log in with an existing one. Then create a new CAPTCHA or select an existing one. If you’re unsure whether TrustCaptcha is right for you, try our CAPTCHA service risk-free for 14 days at no cost.

On the CAPTCHA overview page, you will find all the important information, such as the site key and licence key, and you can also create your API key. Allow your websites to access your CAPTCHA by simply adding them to the access authorised domain list in the CAPTCHA security rules.

CAPTCHA security rules of a demo CAPTCHA.

2. Add the CAPTCHA widget to your form

Drop the TrustCaptcha widget into the HTML form your Fastify route serves. The widget runs the CAPTCHA in the background and adds a hidden tc-verification-token field on submit, which arrives on request.body like any other 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>

The CAPTCHA widget will then be displayed inside your form:

Need detailed information about the CAPTCHA widget integration?
For the full widget reference — including themes, languages, custom design and more — please read our documentation.

Read the documentation

3. Validate the token in your Fastify route

In your Fastify route handler, take the verification token from request.body, look up the result via our Node.js library, and decide whether to accept the request.

First, install our TrustCaptcha Node.js library along with Fastify’s formbody plugin:

Install

bash

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

Then validate the token inside your Fastify route and act on the result:

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 passed — process the request
  return reply.send("Thanks!");
});

Need detailed information about the Fastify CAPTCHA integration?
For full step-by-step instructions — including a reusable preHandler hook for projects with several protected routes — please read our documentation.

Read the documentation

Other backend framework instead of Fastify?
If you use a different framework, pick the matching recipe here. If your framework isn’t listed, your software developers can integrate the verification themselves using our documentation or ask our support team for a pre-built integration.

4. Congratulations 🎉

You are now protected by TrustCaptcha - congratulations!

FAQs

Where in a Fastify app does the CAPTCHA verification go?

Inside the route handler that receives the form submission, or — for several protected routes — inside a preHandler hook (Fastify's per-route middleware equivalent). The CAPTCHA token arrives on request.body under the default name "tc-verification-token".

Do I need a special plugin to receive form submissions?

Yes. Fastify parses JSON automatically, but for application/x-www-form-urlencoded (what a standard HTML form sends), register the @fastify/formbody plugin. Without it, request.body is undefined for form posts and the CAPTCHA verification has nothing to read.

How do I share the API key and the SDK across routes?

Build a single TrustCaptcha instance once at startup, attach it via fastify.decorate("trustCaptcha", instance), and read it from request.server.trustCaptcha inside any route or hook. This avoids rebuilding the SDK per request.

Will Fastify's JSON Schema validation strip the CAPTCHA token?

It can. If you've declared a strict body schema for the route, add tc-verification-token to it (or set additionalProperties: true) so the token isn't removed before your hook or handler reads it.

Can I scope the CAPTCHA hook to a group of routes?

Yes. Register the preHandler globally inside a fastify.register(...) plugin scoped to a route prefix (e.g. /forms), so every route under that prefix runs the verification automatically.

Losing leads to CAPTCHAs?

TrustCaptcha blocks spam and bots, not customers. No puzzles, GDPR-ready, EU-hosted.

Puzzle-free UX

Runs in the background while visitors type — so more people finish your forms and fewer drop off.

GDPR-ready

EU-hosted and privacy-first: no cookies, encrypted transmission, automatic cleanup — with ready-to-use legal resources.

Multi-layer Security

Adaptive protection plus intelligent risk scoring stops abuse early — even when attack traffic spikes.

Full Control

Fine-tune sensitivity, set allow/block lists, and use geoblocking — you decide how strict verification should be.

Protect your Fastify application with TrustCaptcha in just a few steps!

EU-hosted & GDPR-ready
No puzzles
Try free for 14 days

Get started Contact sales