How to Integrate hCaptcha with WordPress

How do you integrate hCaptcha with WordPress?#

To protect WordPress forms from bots, create an hCaptcha account and sitekey, install and activate the official hCaptcha for WP plugin, enter the matching sitekey and secret, and enable the forms you want to protect. This WordPress captcha setup handles server-side token verification for supported integrations. The steps below show how to add hCaptcha to WordPress and test each enabled form before releasing the change.

This guide covers the standard plugin workflow. A custom form or heavily modified site may need the plugin's documented custom-form support or a custom integration.

Simplify protection across your WordPress forms#

• Give visitors a smoother experience. Use hCaptcha Pro's 99.9% Passive mode to reduce visual challenges on the supported WordPress forms you enable and test.
• Let your team share the work. Pro account sharing lets site owners, developers, and agency staff manage hCaptcha sitekeys and settings through their own logins, making ongoing administration easier without sharing credentials.

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:

• Administrator access to the WordPress dashboard.
• WordPress and PHP versions supported by the current hCaptcha for WP release.

These instructions were last validated on September 22, 2026 with hCaptcha for WP 5.3.0.

A sitekey identifies the site and can appear in browser-delivered configuration. The secret authorizes server-side verification and must remain private. Do not paste the secret into page content, client-side scripts, public repositories, or support messages.

Create your account, sitekey, and secret#

1. Start with hCaptcha Pro for fewer challenges and adaptive protection on protected WordPress forms, or use existing compatible hCaptcha credentials.
2. In the hCaptcha dashboard, open Sites and create a sitekey for the WordPress site. Add the production hostname and save the sitekey.
3. 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.
4. Store the secret in an approved credential manager until you add it to WordPress.

The sitekey and secret must belong to the same hCaptcha account. Use separate sitekeys for staging and production when you need separate settings or reporting.

Install hCaptcha for WP#

Use the hCaptcha for WP plugin page as the source for current requirements, releases, and supported integrations. Developers can review or contribute to the hCaptcha WordPress plugin repository. The plugin is also listed in the official hCaptcha integration catalog.

1. In the WordPress dashboard, open Plugins > Add New Plugin.
2. Search for hCaptcha for WP.
3. Confirm that you selected the plugin published by hCaptcha, then choose Install Now.
4. Choose Activate after installation finishes.

For a controlled deployment, install and configure the plugin on staging first. Record the plugin version you tested so later updates can be reviewed against the same baseline.

Add your hCaptcha credentials#

1. Open Settings > hCaptcha > General.
2. Enter the sitekey assigned to this WordPress site.
3. Enter the corresponding secret.
4. Use Check Config to identify invalid credentials or site configuration before saving.
5. Save the settings.

Use credentials assigned to the correct environment. Separate sitekeys for staging and production make test traffic easier to distinguish and reduce the chance that a staging configuration reaches the live site.

Choose the WordPress forms to protect#

Open Settings > hCaptcha > Integrations, find the product or WordPress flow you use, and enable its required form types. Start with the actions that create the most abuse or account risk, such as login, registration, password recovery, comments, checkout, or a public contact form.

Enable one integration at a time when practical. This makes a site or plugin conflict easier to isolate. The official plugin supports WordPress core forms and a changing list of form, commerce, membership, and community plugins; presence on that list does not guarantee compatibility with every customization or extension.

If your form is absent from the integration settings, consult the plugin documentation before assuming it is protected. The basic [hcaptcha] shortcode renders hCaptcha and adds a WordPress nonce, but it does not automatically verify an arbitrary form. A developer must either use the plugin's documented auto-verification option for a compatible front-end POST or AJAX form, or call the plugin's verification helper from the server-side form handler. Block the protected action whenever verification returns an error.

Migrate an existing CAPTCHA configuration#

If the site already uses a supported reCAPTCHA or Turnstile configuration, open Settings > hCaptcha > Tools and run the Migration Wizard. Review the configurations it detects and apply only the migrations you intend to replace. Then disable or remove the old CAPTCHA configuration and repeat the valid and rejected-submission tests for every migrated form.

Verify the integration#

Test as both a signed-out visitor and any relevant signed-in role. Caching, optimization, consent, and role-based plugins can serve different markup or scripts to each audience.

For every enabled form:

1. Load the page in a private browser window and confirm that hCaptcha appears or runs in the configured mode.
2. Complete hCaptcha and submit valid form data. Confirm that the intended action succeeds once.
3. Attempt a submission without a valid hCaptcha result. Confirm that WordPress rejects the action and does not create the comment, account, order, message, or other protected result.
4. Repeat the test after clearing caches and with the site's normal optimization and security plugins enabled.
5. Check browser and WordPress logs for JavaScript errors, blocked requests, or server-side validation errors.

Use the plugin's Pro or Enterprise test mode on staging, then return the integration to live mode before production. A visible widget alone does not prove that the protected action is enforcing verification; the rejected-submission test confirms that the server-side gate is active.

Troubleshoot common setup problems#

The hCaptcha interface does not appear

Confirm that the correct integration and form type are enabled. Then clear page, object, CDN, and browser caches. Temporarily test without script delay, combination, or minification to identify whether an optimization rule is changing the hCaptcha script. Check the browser console and Content Security Policy reports for blocked hCaptcha resources.

A form submits without a valid hCaptcha result

Stop the rollout for that form. Confirm that you enabled the exact integration and form type in use, then repeat the test with caching bypassed. A custom template, AJAX handler, or third-party add-on may avoid the hook used by the plugin. Treat the form as unprotected until a failed hCaptcha attempt is rejected by the server.

Valid visitors cannot submit a form

Run the plugin's configuration check and confirm that the sitekey and secret belong together. Review JavaScript errors, server logs, firewall rules, and outbound connectivity. If the problem began after a WordPress, theme, or plugin update, reproduce it on staging and compare the tested versions before rolling anything back.

The form is not listed under Integrations

Check the current plugin listing and documentation for the exact product and form. A similarly named plugin or a custom-built form is not automatically covered. Use the documented custom-form option where supported, or build an integration that verifies the token server-side.

Choose Pro or discuss an Enterprise deployment#

hCaptcha Pro is the self-service option for this WordPress integration. It adds 99.9% Passive mode, custom themes, more detailed analytics, and multi-user account access. Choose settings based on the protected workflow and test the visitor experience before enabling them broadly.

An organization with higher-volume traffic, centralized identity requirements, custom threat models, risk-score workflows, or contractual service requirements should discuss the deployment with our team. These needs can affect credential management, rollout design, monitoring, and support ownership across multiple WordPress properties.

FAQ#

Does hCaptcha for WP protect every WordPress form automatically?

No. It protects the supported integrations and form types you enable. Verify the exact form in the plugin settings and test that a submission without a valid hCaptcha result is rejected.

Where do I add the hCaptcha sitekey and secret in WordPress?

Open Settings > hCaptcha > General in the WordPress dashboard. Enter the matching sitekey and secret, run Check Config, and save the settings. Keep the secret private.

Can I add hCaptcha to a custom WordPress form?

Yes, when the form fits one of the plugin's documented custom-form paths. The basic [hcaptcha] shortcode does not verify an arbitrary form by itself. Use documented auto-verification for a compatible form or call the plugin's verification helper in the server-side handler.

How do I know the WordPress integration is working?

Test a valid submission and a submission without a valid hCaptcha result. The valid action should complete, while the invalid action should be rejected without creating the protected result.

Does the WordPress plugin work with hCaptcha Pro and Enterprise?

Yes. The official plugin listing states that it supports both plans. The appropriate plan depends on the traffic, controls, deployment model, and service requirements for the site.