Migrating from hCaptcha

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

Key Differences

Feature	hCaptcha	ALTCHA
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");
}

ALTCHA Sentinel (New Implementation)

Frontend:

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

import "altcha";

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.

verify.js

import { verifyServerSignature } from "altcha-lib";

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

// 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("ALTCHA verification failed");
}

For more details, refer to the Server Integration guide.

Migration Steps

1. Remove hCaptcha dependencies

   • Remove the hCaptcha script and widget HTML
   • Delete any hCaptcha verification logic from your backend

2. Install ALTCHA

   • Deploy your ALTCHA Sentinel instance
   • Follow the Widget Integration guide
   • Add the <altcha-widget> to your forms

3. 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.

Further Reading

• ALTCHA Sentinel
• Widget Integration
• Server Integration
• Libraries and Plugins