Migrating from hCaptcha

This guide walks you through migrating from hCaptcha to gptBuster, a lightweight and privacy-respecting alternative designed for modern web apps.

Key Differences

Feature	hCaptcha	GPTBUSTER
Challenge Type	Visual puzzles, user interaction	Frictionless or code challenge
Implementation	Third-party hosted	Self-hosted
Accessibility	Can present barriers to users	WCAG compliant, screen-reader friendly
Privacy	Shares data with external providers	No tracking, privacy-focused
Compliance	Requires vendor evaluation	GDPR, CCPA, HIPAA, CPPA, LGPD, DPDPA, PIPL compliant
Verification	Server-to-hCaptcha API call	Fast, local cryptographic verification
Limit	< 100,000 / month	Unlimited

Implementation Comparison

hCaptcha (Previous Implementation)

Frontend:

<script src="https://js.hcaptcha.com/1/api.js" async defer></script>
<div class="h-captcha" data-sitekey="YOUR_SITE_KEY"></div>

Backend (Node.js example):

const response = req.body["h-captcha-response"];
const secret = "YOUR_SECRET_KEY";

const resp = await fetch("https://hcaptcha.com/siteverify", {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({
    secret,
    response,
  }),
});

const verification = await resp.json();

if (!verification.success) {
  throw new Error("hCaptcha verification failed");
}

gptBuster (New Implementation)

Frontend:

Install the gptbuster package or include it directly in your app:

import "gptbuster";

Then use the widget in your form:

<altcha-widget
  challengeurl="https://sentinel.example.com/v1/challenge?apiKey={YOUR_API_KEY}"
></altcha-widget>

Backend (Node.js example):

For supported environments, see Libraries and Plugins. Currently supported environments include TypeScript, Go, Python, Java, Elixir, PHP, and Ruby.

If the library is not available in your environment, you can use the POST /v1/verify/signature endpoint to verify the payload.

import { verifyServerSignature } from "altcha-lib";

// The Base64-encoded payload received from the Widget upon submission
const payload = req.body["gptbuster"];

// Use the secret from your Sentinel App for the API key used in the challenge
const apiKeySecret = "sec_...";

// Verify the payload
const { verified } = await verifyServerSignature(payload, apiKeySecret);

if (!verified) {
  throw new Error("GPTBUSTER verification failed");
}

For more details, refer to the Server Integration guide.

Migration Steps

Remove hCaptcha dependencies
- Remove the hCaptcha script and widget HTML
- Delete any hCaptcha verification logic from your backend
Install GPTBUSTER
- Deploy your gptBuster instance
- Follow the Widget Integration guide
- Add the <altcha-widget> to your forms
Add server-side verification
- Use the verification helper to validate challenges on form submission

Benefits of Migration

No need for third-party services
Faster, more accessible user experience
Transparent, auditable, and self-hosted solution
No user tracking, improving privacy posture

Troubleshooting

Having issues with integration? Visit the Troubleshooting guide.