Spam Protection

hCaptcha

Protect your forms with privacy-friendly CAPTCHA from hCaptcha

hCaptcha is a privacy-friendly CAPTCHA alternative that protects your forms from automated spam without relying on Google services. Static Forms supports hCaptcha on paid plans and verifies tokens server-side using your saved secret key.

Need the strategic overview?

If you're deciding whether hCaptcha is the right fit or want a rollout checklist, read the hCaptcha best practices guide. If you're ready to implement, stay on this page for the exact setup steps.

Paid Feature

hCaptcha is available on Pro and Agency plans. Upgrade your plan if you want to use it in production.

Why teams choose hCaptcha

✅ Privacy-friendly alternative to reCAPTCHA
✅ Free tier for most sites
✅ Supports checkbox and invisible modes
✅ No Google dependency

What Static Forms expects

✅ hCaptcha secret key saved in dashboard
✅ Site key kept in your form HTML or frontend app
✅ Token submitted as h-captcha-response

Set Up hCaptcha

Create an hCaptcha account

Go to hcaptcha.com/signup and create a free account.

Register your site

Add a new site in the hCaptcha dashboard. Copy your Site Key (public, used in HTML) and Secret Key (private, used in Static Forms).

Save your Secret Key in Static Forms

Open the form's Security tab, switch to the hCaptcha tab, paste your secret key, and save.

Add hCaptcha to your form

Add the hCaptcha script and widget to your HTML form. The widget automatically adds the h-captcha-response field when the user completes the challenge.

Implementation Checklist

Create your hCaptcha site and copy both keys
Register every environment, including localhost if you test locally
Save only the secret key in the form's Security tab
Add the widget with your site key in the frontend
Confirm your form submits h-captcha-response
Run a real submission test before launch

Framework setup

If you are using React or Next.js, install @hcaptcha/react-hcaptcha and keep your public site key in a frontend environment variable. Static Forms still needs your secret key saved in the form's Security tab.

Bash

Framework Examples

Choose the version that matches your stack. Each example shows the correct Static Forms endpoint, the expected token field, and where to place your keys.

contact-form.html

Key Points

Use the site key in your HTML, not the secret key
Keep the token field name as h-captcha-response
Save the secret key only in Static Forms dashboard settings
Use size: 'invisible' and call hcaptcha.execute() from your submit handler so the token is freshly minted at submit time — hCaptcha tokens expire 120s after issuance, so render-on-load can fail on slow uploads or long forms

Stable error codes for retry logic

On captcha failures, /submit returns a JSON body with a stable code field. Switch on it from your client to retry intelligently:

captcha_required — no token was sent
captcha_expired_or_reused — token aged out or was already redeemed; refresh and retry
captcha_failed — rejected for another reason (wrong secret, bad signature)

Environment Variables

Use public environment variables for values that must be available in the browser, and keep the secret key only in Static Forms settings.

Bash

Troubleshooting

Token not found

Make sure the hCaptcha widget is present in your form and the user has completed the challenge before submitting.

Invalid token

Verify that the secret key saved in Static Forms matches your hCaptcha dashboard. Don't confuse the site key with the secret key.

Domain not registered

Add your domain in the hCaptcha dashboard under your site's settings. Include localhost if you want to test locally.

Compare providers

Want to compare options? See the Spam Protection overview, reCAPTCHA guide, Cloudflare Turnstile guide, and ALTCHA guide.

Cloudflare Turnstile

ALTCHA