How to Set Up hCaptcha for XFile Ultra
hCaptcha is a third-party captcha (similar role to reCAPTCHA). You create a site in the hCaptcha dashboard, then paste the site key and secret key into XFile Ultra under Captcha & abuse.
Where to find it in XFile Ultra
Admin → Settings → Settings (first / Main tab) → Captcha & abuse
1. Set Provider to hCaptcha
2. Paste hCaptcha site key and hCaptcha secret key
3. Enable surfaces under Captcha on forms
4. Save settings
Fields in XFile Ultra
| Field in admin | Setting key | From hCaptcha |
|---|---|---|
| hCaptcha site key | hcaptcha_site_key |
Sitekey / Site key |
| hCaptcha secret key | hcaptcha_secret_key |
Secret |
Env fallbacks: NEXT_PUBLIC_HCAPTCHA_SITE_KEY and HCAPTCHA_SECRET_KEY.
Step 1 — Create a site in hCaptcha
1. Open the hCaptcha dashboard and sign in (or create an account)
2. Go to Sites (sometimes labeled Add site)
3. Create a new site
4. Hostnames: add your domain without https://
- Example: example.com
- Add www.example.com if you use www
5. Choose difficulty / type defaults unless you have a reason to change them
6. Save the site
7. Open the site details and copy:
- Sitekey (public)
- Secret (private — also available under account / site secret depending on UI)
Never expose the secret in the browser or theme files.
Docs: hCaptcha docs.
Step 2 — Paste keys into XFile Ultra
1. Go to Admin → Settings → Settings (first / Main tab) → Captcha & abuse
2. Provider → hCaptcha
3. Paste Sitekey → hCaptcha site key
4. Paste Secret → hCaptcha secret key
5. Enable the forms you want under Captcha on forms
6. Save settings
Step 3 — Verify it works
1. Open a protected form in a private window (example: /contact)
2. Confirm the hCaptcha widget appears
3. Complete the challenge and submit successfully
4. Submit without completing it — the form should reject
Domains checklist
| Host in hCaptcha | When |
|---|---|
example.com |
Primary |
www.example.com |
If www is used |
localhost |
Local testing (if allowed by your hCaptcha plan/settings) |
Common problems
Invalid site key
Typo, wrong site selected, or hostname not attached to that site. Re-open the site in the dashboard and re-copy the sitekey.
Widget OK, every verify fails
Site key and secret reversed, or secret from another site/account. Swap or re-copy both from the same site.
Domain not allowed
Add the exact hostname visitors use (apex vs www).
Still on Text / Image / Google captcha
Provider must be hCaptcha, and the form toggle under Captcha on forms must be on.
Secret blank after save
Normal. Leave empty to keep the stored secret.