TrustComponent
Hapi
TrustCaptcha · Bot protection

Hapi CAPTCHA Integration

Set up a Hapi CAPTCHA in a route or pre-handler with a few lines of TypeScript. TrustCaptcha stops bot spam on logins, signups and contact forms, and your Joi schemas and payload parsing keep working. EU-hosted, GDPR-compliant, 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 pick an existing one. If you want to try TrustCaptcha first, every plan comes with a 14-day free trial.

The CAPTCHA overview page shows your site key and license key, and you create your API key there. Add your website’s domains to the authorized domains in the CAPTCHA security rules so they can use your CAPTCHA.

Start of the CAPTCHA creation form.
CAPTCHA security rules of a demo CAPTCHA.

2. Add the CAPTCHA widget to your form

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

CAPTCHA start

Need detailed information about the CAPTCHA widget integration?
Our documentation has the full widget reference, including themes, languages and custom design.

Read the documentation

3. Validate the token in your Hapi route

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

First, install our TrustCaptcha Node.js library:

Install
bash
npm i @hapi/hapi @trustcomponent/trustcaptcha-nodejs

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

server.ts
TypeScript
import Hapi from "@hapi/hapi";
import { TrustCaptcha } from "@trustcomponent/trustcaptcha-nodejs";

const server = Hapi.server({ port: 8080 });

server.route({
  method: "POST",
  path: "/contact",
  handler: async (request, h) => {
    const payload = request.payload as Record<string, string>;
    const token = payload["tc-verification-token"] ?? "";

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

    // CAPTCHA passed — process the request
    return "Thanks!";
  },
});

await server.start();

Need detailed information about the Hapi CAPTCHA integration?
For full step-by-step instructions, including a reusable pre-extension for projects with several protected routes, please read our documentation.

Read the documentation

Other backend framework instead of Hapi?
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.

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. Test your integration

TrustCaptcha is now active. Send a test request and check that it goes through.

CAPTCHA done

FAQs

Where does the Hapi CAPTCHA check go?
Inside the route handler that receives the form submission or, for several protected routes, inside a route-level pre-extension. Both have access to request.payload, where the CAPTCHA token (default name: "tc-verification-token") arrives like any other field.
Do I need a payload-parser plugin?
No. Hapi parses application/x-www-form-urlencoded and application/json automatically: request.payload is already the parsed object, so no extra plugin is required to read the CAPTCHA token.
How do I run the verification before the route handler?
Use Hapi's pre extension. Define a small async function that reads the token, calls our Node.js library and returns either h.continue (proceed) or h.response(...).takeover() (short-circuit with a 400). Add it to the route's options under pre.
Will Joi validation strip the CAPTCHA token from the payload?
It can. If you validate the payload with @hapi/joi (or joi), declare tc-verification-token in the schema or call .unknown(true) so the token is preserved before your pre-extension or handler reads it.
How do I share the SDK across many routes?
Build a single TrustCaptcha instance once at startup and store it on the server's app object: server.app.trustCaptcha = new TrustCaptcha({ apiKey }). Inside any pre-extension or handler, read it via request.server.app.trustCaptcha, with no rebuild per request.
Losing leads to CAPTCHAs?

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

CAPTCHA start
CAPTCHA done
No puzzles for visitors
The check runs in the background while visitors type, so more people finish your forms instead of giving up.
GDPR-compliant
Hosted in the EU, no cookies, encrypted transmission and automatic data deletion. Every customer gets a Data Processing Agreement.
Multi-layer security
Adaptive proof-of-work and risk scoring stop abuse early, even when attack traffic spikes.
Full control
Set the sensitivity, keep allow and block lists and use geoblocking. You decide how strict the check is.

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

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