hCaptcha for WP

FAQ

¿Cómo uso el plugin hCaptcha?

El plugin hCaptcha es compatible con el núcleo de WordPress y muchos plugins con formularios de forma automática. Debes seleccionar los formularios compatibles en la página de ajustes de integraciones de hCaptcha.

Para casos no estándar, puedes utilizar el código corto [hcaptcha] proporcionado por el plugin.

Por ejemplo, admitimos Contact Forms 7 de forma automática. Sin embargo, a veces un tema puede modificar el formulario. En este caso, puedes añadir manualmente el código abreviado [cf7-hcaptcha] al formulario CF7.

Para que hCaptcha funcione, el shortcode debe estar dentro de la etiqueta …

…

tag.

How do I migrate from reCAPTCHA or Turnstile?

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.

How do I use the new AI / Abilities features?

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" \
"https://example.com/wp-json/wp-abilities/v1/abilities/hcaptcha/get-threat-snapshot/run?input[window]=55d"

The response includes:
* overall metrics (total requests, failure rate)
* confidence and top error vectors
* breakdown by error type and form source
* a list of top offenders (if present)

Example (simplified):

{
  "metrics": { "total": 353, "failed": 215, "fail_rate": "0.61" },
  "signals": { "confidence": "high", "top_vectors": ["empty", "spam"] },
  "breakdown": {
    "errors": { "empty": 160, "spam": 16 },
    "offenders": [
      {
        "offender_id": "a1376a016c4156933c4d49b0bc56fa01",
        "type": "ip",
        "count": 2
      }
    ]
  }
}

** 2. Block abusive offenders **

If an offender appears suspicious, you can block it using its offender_id.

Using WP-CLI:

wp ability run hcaptcha/block-offenders \
--input='{"offender_ids":["a1376a016c4156933c4d49b0bc56fa01"]}' \
--user=admin

Using REST API (authenticated):

curl --globoff -u "USER:APP_PASSWORD" \
"https://example.com/wp-json/wp-abilities/v1/abilities/hcaptcha/block-offenders/run?input[offender_ids][]=a1376a016c4156933c4d49b0bc56fa01"

Example response:

{
  "blocked": ["a1376a016c4156933c4d49b0bc56fa01"],
  "effective_until": "2026-01-01T22:22:09Z"
}

** What is offender_id? **

offender_id is a stable hash of the IP address.

Raw IP addresses are never exposed to automation clients or AI agents.

This allows privacy-safe analysis and blocking, while still enabling deterministic enforcement.

** Can AI agents use this automatically? **

Yes.
You can point an AI agent to a WordPress site with Abilities enabled and instruct it to:
* discover available abilities
* collect threat statistics
* decide whether activity looks abusive
* block the most active offenders

Internally, the agent performs the same commands shown above (wp ability list, get-threat-snapshot, block-offenders).

** 3. Export plugin settings **

You can export current plugin settings as JSON (optionally including keys) for backup or migration.

Using WP-CLI:

wp ability run hcaptcha/export-settings --include_keys --user=admin

Using REST API (authenticated):

curl --globoff -u "USER:APP_PASSWORD" \
"https://example.com/wp-json/wp-abilities/v1/abilities/hcaptcha/export-settings/run?input[include_keys]=1"

** 4. Import plugin settings **

Import settings from a JSON file path on the server. Use allow_keys to apply the keys block and dry_run to validate without saving.

Using WP-CLI:

wp ability run hcaptcha/import-settings --allow_keys --dry-run=false --user=igor --input_file=1.json

Using REST API (authenticated):

curl --globoff -u "USER:APP_PASSWORD" \
"https://example.com/wp-json/wp-abilities/v1/abilities/hcaptcha/import-settings/run?input[input_file]=%2Fpath%2Fto%2Fhcaptcha-settings.json&input[allow_keys]=1&input[dry_run]=0"

WP-CLI commands for exporting and importing settings

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=<path> — 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 JSON without saving.
* --allow-keys — allow importing keys from the keys block.

No es compatible con el plugin X. ¿Cómo puedo conseguir que se añada compatibilidad para él?

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.

¿El shortcode [hcaptcha] tiene argumentos?

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"]

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 the section «How to automatically verify an arbitrary form». By default, auto="false".

The argument force=»true|false» allows forcing verification of hCaptcha widget before submitting the form. By default, force="false".

The argument size=»normal|compact|invisible» allows setting the size of hCaptcha widget. By default, size="normal".

Cómo añadir hCaptcha a un formulario arbitrario

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:

<form method="post">
    <input type="text" name="test_input">
    <input type="submit" value="Send">
    [hcaptcha]
</form>

If you create the form programmatically, insert the following statement inside it:

?>
<form method="post">
    <input type="text" name="test_input">
    <input type="submit" value="Send">
    <?php echo do_shortcode( '[hcaptcha]' ); ?>
</form>
<?php

Secondly, verify the result of hCaptcha challenge.

$result = \HCaptcha\Helpers\API::verify_request();

if ( null !== $result ) {
    echo esc_html( $result );
    // Block processing of the form.
}

Cómo verificar automáticamente un formulario arbitrario

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 ajax="true"]

¿Cómo bloquear completamente hCaptcha en una página específica?

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 ( '/my-account/' === $url ) {
    return false;
  }

  return $activate;
}

add_filter( 'hcap_activate', 'my_hcap_activate' );

How do I block hCaptcha scripts everywhere except on a specific page?

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 );

Omitir la verificación hCaptcha en un formulario específico

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
$source: ‘affiliates/affiliates.php’
$form_id: ‘login’ or ‘register’

Back In Stock Notifier
$source: ‘back-in-stock-notifier-for-woocommerce/cwginstocknotifier.php’
$form_id: product_id

BBPress
$source: ‘bbpress/bbpress.php’
$form_id: ‘new_topic’, ‘reply’, ‘login’, ‘register’ or ‘lost_password’

Beaver Builder
$source: ‘bb-plugin/fl-builder.php’
$form_id: ‘contact’ or ‘login’

Blocksy
$source: ‘blocksy’
$form_id: ‘newsletter-subscribe’, ‘$layer[«__id»]’, or ‘product_id

Brizy
$source: ‘brizy/brizy.php’
$form_id: ‘form’

BuddyPress
$source: ‘buddypress/bp-loader.php’
$form_id: ‘create_group’ or ‘register’

Classified Listing
$source: ‘classified-listing/classified-listing.php’
$form_id: ‘contact’, ‘login’, ‘lost_password’ or ‘register’

Divi
$source: ‘Divi’
$form_id: post_id for comment form, ‘contact’, ‘email_optin’, or ‘login’

Download Manager
$source: ‘download-manager/download-manager.php’
$form_id: post_id of download item in the admin

Easy Digital Downloads
$source: ‘easy-digital-downloads/easy-digital-downloads.php’
$form_id: ‘checkout’, ‘login’, ‘lost_password’ or ‘register’

Elementor Pro
$source: ‘elementor-pro/elementor-pro.php’
$form_id: Form ID set for the form Content->Additional Options or ‘login’

Events Manager
$source: ‘events-manager/events-manager.php’
$form_id: event_id

Icegram Express
$source: ‘email-subscribers/email-subscribers.php’
$form_id: form_id

Customer Reviews for WooCommerce
$source: ‘customer-reviews-woocommerce/ivole.php’
$form_id: review or q&a

Jetpack
$source: ‘jetpack/jetpack.php’
$form_id: ‘contact_$form_hash’

Kadence Form
$source: ‘kadence-blocks/kadence-blocks.php’
$form_id: post_id

Kadence Advanced Form
$source: ‘kadence-blocks/kadence-blocks.php’
$form_id: form_id

LearnDash
$source: ‘sfwd-lms/sfwd_lms.php’
$form_id: ‘login’, ‘lost_password’ or ‘register’

LearnPress
$source: ‘learnpress/learnpress.php’
$form_id: ‘checkout’, »login’, or ‘register’

Login/Signup Popup
$source: ‘easy-login-woocommerce/xoo-el-main.php’
$form_id: ‘login’, or ‘register’

MemberPress
$source: ‘memberpress/memberpress.php’
$form_id: ‘login’ or ‘register’

Paid Memberships Pro
$source: ‘paid-memberships-pro/paid-memberships-pro.php’
$form_id: ‘checkout’ or ‘login’

Passster
$source: ‘content-protector/content-protector.php’
$form_id: area_id

Password Protected
$source: ‘password-protected/password-protected.php’
$form_id: ‘protect’

Profile Builder
$source: ‘profile-builder/index.php’
$form_id: ‘login’, ‘lost_password’ or ‘register’

Simple Membership
$source: ‘simple-membership/simple-wp-membership.php’
$form_id: ‘login’, ‘lost_password’ or ‘register’

Subscriber
$source: ‘subscriber/subscriber.php’
$form_id: ‘form’

Support Candy
$source: ‘supportcandy/supportcandy.php’
$form_id: ‘form’

Theme My Login
$source: ‘theme-my-login/theme-my-login.php’
$form_id: ‘login’, ‘lost_password’ or ‘register’

Tutor LMS
$source: ‘tutor/tutor.php’
$form_id: ‘checkout’, »login’, ‘lost_password’ or ‘register’

Ultimate Addons
$source: ‘ultimate-elementor/ultimate-elementor.php’
$form_id: ‘login’ or ‘register’

Ultimate Member
$source: ‘ultimate-member/ultimate-member.php’
$form_id: form_id or ‘password’

UsersWP
$source: ‘userswp/userswp.php’
$form_id: ‘forgot’, ‘login’ or ‘register’

WooCommerce Germanized
$source: ‘woocommerce-germanized/woocommerce-germanized.php’
$form_id: ‘return_request’

WooCommerce Wishlist
$source: ‘woocommerce-wishlists/woocommerce-wishlists.php’
$form_id: ‘form’

wpDiscuz
$source: ‘wpdiscuz/class.WpdiscuzCore.php’
$form_id: post_id

WPForms
$source: ‘wpforms-lite/wpforms.php’ or ‘wpforms/wpforms.php’
$form_id: form_id

wpForo
$source: ‘wpforo/wpforo.php’
$form_id: ‘new_topic’ for a new topic form and topicid for a reply form. Topicid can be found in HTML code searching for ‘data-topicid’ in Elements.

Wordfence Login Security
$source: ‘wordfence-login-security/wordfence-login-security.php’
$form_id: ‘login’

Wordfence Security
$source: ‘wordfence/wordfence.php’
$form_id: ‘login’

WordPress Core
$source: ‘WordPress’
$form_id: post_id for comment form, ‘login’, ‘lost_password’, ‘password_protected’, or ‘register’

WooCommerce
$source: ‘woocommerce/woocommerce.php’
$form_id: ‘checkout’, ‘login’, ‘lost_password’, ‘order_tracking’, or ‘register’

Below is an example of how to skip the hCaptcha widget on a Gravity Form with id = 1.

/**
 * Filters the protection status of a form.
 *
 * @param string|mixed $value   The protection status of a form.
 * @param string[]     $source  Plugin(s) serving the form.
 * @param int|string   $form_id Form id.
 *
 * @return bool
 */
function hcap_protect_form_filter( $value, $source, $form_id ): bool {
  $value = (bool) $value;

  if ( ! in_array( 'gravityforms/gravityforms.php', $source, true ) ) {
    // The form is not sourced by Gravity Forms plugin.
    return $value;
  }

  if ( 1 !== (int) $form_id ) {
    // The form has id !== 1.
    return $value;
  }

  // Turn off protection for a Gravity form with id = 1.
  return false;
}

add_filter( 'hcap_protect_form', 'hcap_protect_form_filter', 10, 3 );

¿Cómo puedo mostrar el widget hCaptcha instantáneamente?

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 means delay until user interaction.
 */
function my_hcap_delay_api( $delay ): int {
  return 0;
}

add_filter( 'hcap_delay_api', 'my_hcap_delay_api' );

How can I load the hCaptcha API script only when a specific element is visible?

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 $delay_api_selector;
    }

    $selectors = [
        '.comment-form', // WP comment form.
        '.elementor-form', // Elementor Pro.
        '.wpcf7-form', // Contact Form 7.
        '.fluentform, .frm-fluent-form', // Fluent Forms.
        '.nf-form-cont', // Ninja Forms.
        '.es_subscription_form, .es-form-field-container, .ig_popup', // Icegram Express Forms.
        '.cr-reviews-ajax-reviews, .cr-qna-block', // Customer Reviews.
    ];

    return implode( ', ', $selectors );
} );

How can I delay the hCaptcha API script until a custom event?

Developers can use the hcap_delay_api_event filter to opt into custom event-based API loading for specific integrations.

When the filter returns a non-empty event name, hCaptcha waits for hCaptchaBeforeAPI, then listens for that custom event on document. The default delay timer and built-in user interaction listeners are skipped. Your integration must dispatch the event when it is ready to load the hCaptcha API.

Scope this filter carefully to only the pages or forms where you also dispatch the event.

/**
 * Filters the custom browser event name used to load the hCaptcha API script.
 *
 * @param string|mixed $delay_api_event Custom browser event name.
 */
add_filter(
  'hcap_delay_api_event',
  static function ( $delay_api_event ): string {
    if ( ! is_singular() || ! has_block( 'jetpack/contact-form', get_queried_object() ) ) {
      return (string) $delay_api_event;
    }

    return 'hcap-load-api';
  }
);

// Later, when the form is interacted with:
// document.dispatchEvent( new CustomEvent( 'hcap-load-api' ) );

¿Cómo configurar el idioma de hCaptcha mediante programación?

De forma por defecto, hCaptcha utiliza el idioma del usuario según lo informado por el navegador. Sin embargo, en sitios multilingües, puedes anular esta opción para configurar el idioma de hCaptcha de modo que coincida con el idioma de la página actual. Para ello, puede utilizar el siguiente filtro:

/**
 * 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' );

How to denylist certain IPs

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', 'my_hcap_denylist_ip', 10, 2 );

How does hCaptcha determine the visitor IP address?

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 starts empty and an admin notice asks you to review it.

Cómo incluir en la lista blanca determinadas direcciones IP

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 true;
  }

  return $allowlisted;
}

add_filter( 'hcap_whitelist_ip', 'my_hcap_allowlist_ip', 10, 2 );

¿Cómo cambio la apariencia del menú de administración?

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;
}

add_filter( 'hcap_settings_init_args', 'hcap_settings_init_args_filter' );


$args array has the following fields:

mode: 'pages' or 'tabs' (default 'pages') — the appearance of the admin menu;
parent: a string — the parent menu item. Default '' for 'pages' mode and 'options-general.php' for 'tabs' mode;
position: a number — the position of the menu item. Default 58.990225 for 'pages' mode. It Has no effect on 'tabs' mode;

Where do I report security bugs found in this plugin?

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.

¿Dónde puedo obtener más información sobre hCaptcha?

Please see our website.

How can I rerun the setup wizard?

Use the plugin-generated «Restart wizard» onboarding link from the admin area. Onboarding setup URLs are nonce-protected and should not be crafted manually.