hCaptcha for WP

The hCaptcha plugin supports WordPress core and many plugins with forms automatically. You should select the supported forms on the hCaptcha Integrations settings page. For non-standard cases, you can use the [hcaptcha] shortcode provided by the plugin. For example, we support Contact Forms 7 automatically. However, sometimes a theme can modify the form. In this case, you can manually add the [cf7-hcaptcha] shortcode to the CF7 form. To make hCaptcha work, the shortcode must be inside the … tag.

Go to Settings → hCaptcha → Tools and use the Migration Wizard. It scans your site for existing CAPTCHA providers, shows what can be migrated, and applies the changes in one click.

hCaptcha exposes selected security actions via the WordPress Abilities API for use with automation tools, WP-CLI, and AI agents, making it suitable for agencies managing multiple WordPress sites. Requires WordPress 6.9 or newer. The typical workflow consists of two steps: inspect threats and block offenders. ** 1. Inspect recent threat activity ** You can request an aggregated threat snapshot for a given time window. Using WP-CLI: wp ability run hcaptcha/get-threat-snapshot --input='{"window":"55d"}' --user=admin Using REST API (authenticated): curl --globoff -u "USER:APP_PASSWORD" \…

The plugin also adds the wp hcaptcha export and wp hcaptcha import commands. Export settings ` wp hcaptcha export –pretty > hcaptcha-settings.json wp hcaptcha export –include-keys –file=./hcaptcha-settings.json ` Parameters: * --include-keys — include the site_key and secret_key values. * --pretty — pretty-print JSON for readability. * --file= — write JSON to a file instead of STDOUT. Import settings ` wp hcaptcha import ./hcaptcha-settings.json wp hcaptcha import ./hcaptcha-settings.json –dry-run wp hcaptcha import ./hcaptcha-settings.json –allow-keys ` Parameters: * --dry-run — validate the…

Open a PR on GitHub: or just email the authors of plugin X. Adding hCaptcha support is typically quite a quick task for most plugins.

Full list of arguments: [hcaptcha action="my_hcap_action" name="my_hcap_name" auto="true|false" ajax="true|false" force="true|false" theme="light|dark|auto" size="normal|compact|invisible" honeypot="true|false"] The shortcode adds not only the hCaptcha div to the form but also a nonce field. You can set your own nonce action and name. For this, use arguments in the shortcode: [hcaptcha action="my_hcap_action" name="my_hcap_name"] and in the verification: $result = \HCaptcha\Helpers\API::verify_post( 'my_hcap_name', 'my_hcap_action' ); For the explanation of the auto=”true|false” argument, see…

First, add the hCaptcha snippet to the form. If you create the form as an HTML block in the post content, insert the shortcode [hcaptcha] inside it. It may look like this: [hcaptcha] If you create the form programmatically, insert the following statement inside it: ?>

Arbitrary user forms can be verified easily. Just add auto="true" or auto="1" to the shortcode: [hcaptcha auto="true"] and insert this shortcode into your form. Auto-verification works with forms sent by POST on frontend only. It works with forms in the post content and in widgets. You can add also force="true" or force="1" argument to prevent sending a form without checking the hCaptcha. [hcaptcha auto="true" force="true"] Arbitrary forms can also be verified in ajax via the ajax argument. There is no need to specify auto="true" in this case, as ajax implies auto="true". [hcaptcha…

hCaptcha starts early, so you cannot use standard WP functions to determine the page. For instance, to block it on my-account page, add the following code to your plugin’s (or mu-plugin’s) main file. This code won’t work being added to a theme’s functions.php file. /** * Filter hCaptcha activation flag. * * @param bool|mixed $activate The activate flag. * * @return bool */ function my_hcap_activate( $activate ): bool { $status = (bool) $status; $url = isset( $_SERVER['REQUEST_URI'] ) ? filter_var( wp_unslash( $_SERVER['REQUEST_URI'] ), FILTER_SANITIZE_FULL_SPECIAL_CHARS ) : ''; if (…

As an example, to block hCaptcha scripts everywhere except on the contact page: /** * Block inline styles. * * @return void */ function hcap_block_inline_styles() { if ( is_page( 'contact' ) ) { return; } $hcaptcha = hcaptcha(); remove_action( 'wp_head', [ $hcaptcha, 'print_inline_styles' ] ); remove_filter( 'wp_resource_hints', [ $hcaptcha, 'prefetch_hcaptcha_dns' ] ); } add_action( 'wp_head', 'hcap_block_inline_styles', 0 );

The plugin has a filter to skip adding and verifying hCaptcha on a specific form. The filter receives three parameters: current protection status (‘true’ by default), source, and form_id. The source is the plugin’s slug (like ‘directory/main-plugin-file.php’), the theme name (like ‘Avada’) or the WordPress core (like ‘WordPress’). The form_id is the form_id for plugins like Gravity Forms or WPForms, the post id for comments, or a general name of the form when the form does not have an id (like WordPress core login form). Filter arguments for some plugins/forms are listed below. Affiliates…

The plugin loads the hCaptcha script with a delay until user interaction: mouseenter, click, scroll, or touch. This significantly improves Google Pagespeed Insights score. To load the hCaptcha widget instantly, you can use the following filter: /** * Filters delay time for hCaptcha API script. * * Any negative value will prevent the API script from loading at all, * until user interaction: mouseenter, click, scroll, or touch. * This significantly improves Google Pagespeed Insights score. * * @param int|mixed $delay Number of milliseconds to delay hCaptcha API script. * Any negative value…

To load the hCaptcha API script only when a WordPress comment form is visible, you can use the followign filter: /** * Filters delay API selector. * * When set, the hcaptcha.js script will be loaded only when the specified element is visible. * This can improve page load performance by deferring the API script until it's necessary. * * @param string|mixed $delay_api_selector CSS selector of the element to observe. */ add_filter( 'hcap_delay_api_selector', static function ( $delay_api_selector ) { $delay_api_selector = (string) $delay_api_selector; if ( is_admin() || is_login() ) { return…

Developers can use the hcap_delay_api_event filter to opt into event-based API loading. Return true to use the built-in trigger. It loads the API after pointer or keyboard interaction with a protected HTML form. Tab navigation into the form is supported, while programmatic focus is ignored. This works with WordPress core login, lost password, and registration forms, Jetpack forms, and other integrations that render hCaptcha inside a form. add_filter( 'hcap_delay_api_event', '__return_true' ); Non-empty strings remain custom event names. In that mode, hCaptcha waits for hCaptchaBeforeAPI, then…

hCaptcha defaults to using the user’s language as reported by the browser. However, on multilingual sites you can override this to set the hCaptcha language to match the current page language. For this, you can use the following filter: /** * Filters hCaptcha language. * * @param string|mixed $language Language. */ function my_hcap_language( $language ): string { $language = (string) $language; // Detect page language and return it. $page_language = 'some lang'; // Detection depends on the multilingual plugin used. return $page_language; } add_filter( 'hcap_language', 'my_hcap_language' );

You can use the following filter. It should be added to your plugin’s (or mu-plugin’s) main file. This filter won’t work being added to a theme’s functions.php file. /** * Filter the user IP to check if it is denylisted. * For denylisted IPs, any form submission fails. * * @param bool|mixed $denylisted Whether IP is denylisted. * @param string $ip IP. * * @return bool */ function my_hcap_denylist_ip( $denylisted, $ip ): bool { $denylisted = (bool) $denylisted; // Denylist some IPs. if ( '8.8.8.8' === $ip ) { return true; } return $denylisted; } add_filter( 'hcap_blacklist_ip'…

hCaptcha uses REMOTE_ADDR by default. If your site is behind a trusted proxy or CDN, go to Settings → hCaptcha → Anti-Spam → Access Control and select only the IP headers your edge service overwrites or strips from direct client requests. Forwarding headers such as X-Forwarded-For, CF-Connecting-IP, and X-Real-IP can be spoofed when they pass through from the browser unchanged. Do not enable a header unless your hosting stack makes it trustworthy before WordPress receives the request. On upgrade, custom hcap_trusted_address_headers filters are migrated into this setting. Otherwise the setting…

You can use the following filter. It should be added to your plugin’s (or mu-plugin’s) main file. This filter won’t work being added to a theme’s functions.php file. /** * Filter user IP to check if it is allowlisted. * For allowlisted IPs, hCaptcha will not be shown. * * @param bool|mixed $allowlisted Whether IP is allowlisted. * @param string $ip IP. * * @return bool */ function my_hcap_allowlist_ip( $allowlisted, $ip ): bool { $allowlisted = (bool) $allowlisted; // Allowlist local IPs. if ( false === $ip ) { return true; } // Allowlist some other IPs. if ( '1.1.1.1' === $ip ) { return…

Starting from 4.1.0, the admin menu was moved to the top level with subpages. You can customize this by returning it to the previous location in the admin Settings section or tweaking its appearance. To do this, use the following filter to your plugin’s (or mu-plugin’s) main file. This code won’t work being added to a theme’s functions.php file. /** * Filter the settings system initialization arguments. * * @param array|mixed $args Settings system initialization arguments. */ function hcap_settings_init_args_filter( $args ): array { $args = (array) $args; $args['mode'] = 'tabs'; return $args…

Please report security vulnerabilities by email to: security@hcaptcha.com When reporting a vulnerability, please include as much information as possible to help us reproduce and investigate the issue, such as: A clear description of the vulnerability Steps to reproduce Proof-of-concept or exploit code (if available) Affected versions We will review your report and respond as quickly as possible.