How to Integrate hCaptcha with XenForo

How do you integrate hCaptcha with XenForo?#

Configure XenForo's native hCaptcha integration under Enable CAPTCHA for guests, then enter your hCaptcha sitekey and secret. XenForo includes the rendering and validation code, so no separate add-on or template snippet is required.

hCaptcha is available as XenForo's native CAPTCHA provider, so supported installations do not require a separate add-on.

These instructions were last validated on September 16, 2026 with XenForo 2.3.13. Check XenForo announcements before deploying a newer version.

Make XenForo guest and member workflows smoother#

• Ask less of legitimate participants. With hCaptcha Pro's 99.9% Passive mode, fewer than 0.1% of legitimate users receive a challenge on registration and guest workflows that invoke XenForo's native provider.
• Increase verification when activity looks suspicious. Pro adjusts challenge difficulty as risk rises, helping you keep participation less disruptive while applying stronger checks to higher-risk attempts.

New Pro sitekeys use 99.9% Passive by default. For an existing sitekey upgraded to Pro, select that mode under Behavior in the hCaptcha dashboard.

Before you start#

You need:

• A supported XenForo 2.2 or 2.3 community with administrator access.
• An hCaptcha account that can create a sitekey and securely manage its matching secret.
• Access to test registration, guest posting, contact, password, and add-on workflows that use XenForo CAPTCHA.
• A current inventory of custom styles and add-ons that change public forms.

Native support makes the older third-party hCaptcha add-on unnecessary on supported XenForo releases. Remove or disable overlapping CAPTCHA add-ons before testing the core provider.

Create your hCaptcha credentials#

1. Start with hCaptcha Pro for fewer challenges and adaptive protection on protected XenForo member and guest workflows, or use existing compatible hCaptcha credentials.
2. Create a sitekey for the XenForo hostname.
3. Add the production hostname and any separate staging hostname assigned to that sitekey.
4. Use the matching secret saved during account setup. If it is unavailable, generate a replacement in dashboard Settings, save it securely, and update integrations using the old secret; generating a new secret rotates it.
5. Restrict Admin control panel access to people who need to manage the integration.

The sitekey renders hCaptcha in the browser. The secret authorizes server-side verification and must stay in server-managed XenForo configuration. We list XenForo in our integration catalog and integrations-list repository.

Configure native hCaptcha in XenForo#

XenForo's CAPTCHA documentation describes the general provider selection path. The option label may appear under Basic options or Basic board information, depending on the XenForo release.

1. Sign in to the XenForo Admin control panel.
2. Open Setup > Options.
3. Select Basic options or Basic board information.
4. Show advanced options if Enable CAPTCHA for guests is hidden.
5. Select hCaptcha as the CAPTCHA provider.
6. Enter the hCaptcha sitekey and secret.
7. Enable Use invisible hCaptcha only when that behavior fits the sitekey and user experience.
8. Save the settings.

XenForo 2.2 introduced both visible and invisible hCaptcha. Invisible mode also adds hCaptcha privacy and terms attribution through XenForo's privacy-policy handling.

Verify the XenForo integration#

XenForo renders the selected provider wherever its guest CAPTCHA check is used. Its developer contract requires a server-side CAPTCHA validation check before an action creates or saves data.

1. Open registration in a private browser window and confirm that the selected hCaptcha mode initializes.
2. Complete hCaptcha and submit valid data. Confirm that the account workflow proceeds once.
3. Submit without a valid response and confirm that XenForo blocks the request.
4. Repeat accepted and rejected tests for guest posting, contact, password, and applicable add-on forms.
5. Retest custom styles, mobile layouts, caches, consent tools, and Content Security Policy settings.

XenForo normally omits CAPTCHA for logged-in users. An add-on can force or add CAPTCHA, but it must render the field and run XenForo's validation before changing data. Review those add-ons separately.

Troubleshoot common XenForo problems#

The CAPTCHA option is missing

Scroll to the bottom of the option group and enable advanced options. Confirm that the community runs XenForo 2.2 or later and that the administrator has permission to manage options.

hCaptcha renders, but every request fails

Confirm that the sitekey and secret belong to the same hCaptcha account and cover the active hostname. Check outbound HTTPS access from the XenForo server and inspect server errors without exposing the secret.

hCaptcha appears on registration but not guest posts

Confirm that guest posting is enabled and that the relevant XenForo template and action invoke the core CAPTCHA check. Registration success does not establish coverage for every guest form.

A custom add-on form bypasses hCaptcha

Ask the add-on maintainer whether the form uses XenForo's CAPTCHA template tag and server-side validation method. Core configuration cannot protect a custom action that never calls the CAPTCHA system.

Choose Pro or discuss an Enterprise deployment#

hCaptcha Pro is the self-service path for XenForo. It includes 99.9% Passive mode, custom themes, more detailed analytics, and multi-user account access.

Organizations operating several communities, higher-volume forums, risk-score workflows, custom threat models, centralized access requirements, or contractual service needs should plan the deployment with our team. Review XenForo compatibility, credential ownership, workflow coverage, and rollout monitoring before launch.

FAQ#

Which XenForo versions support hCaptcha?

Use a supported XenForo release that includes the native hCaptcha provider. Check XenForo's current documentation and announcements before upgrading.

Does XenForo require an hCaptcha add-on?

No. Supported XenForo releases include hCaptcha natively. The older third-party integration is unnecessary for the standard setup.

Does XenForo support invisible hCaptcha?

Yes. XenForo 2.2 and later provide an invisible option alongside the visible provider. Test its privacy attribution and every protected workflow before launch.

Where is the hCaptcha setting in XenForo?

Open Setup > Options, select the basic options group, show advanced options when needed, and find Enable CAPTCHA for guests.

Which XenForo forms use hCaptcha?

XenForo uses the configured provider where its guest CAPTCHA check is invoked, including registration and applicable guest workflows. Custom add-ons must integrate with XenForo's rendering and server-side validation contract.