Gravity Forms hCaptcha Premium Add-on Setup Guide

What the Add-on Does

hCaptcha is a bot detection service that asks visitors to prove they are human, either with a checkbox or completely in the background. The add-on adds an hCaptcha field to Gravity Forms. When the form is submitted, your server sends the answer to hCaptcha together with your secret and only accepts the entry when hCaptcha confirms it. Bots that post straight to your form without loading the page never get a valid answer, so they never get an entry.

Everything that matters for real sites is handled: AJAX forms, multi-page forms, Save and Continue, several forms on one page, forms that come back with an error, a slow or unreachable hCaptcha, and the Gravity Forms reCAPTCHA field on the same site. Each entry keeps the result, and Enterprise accounts can refuse entries above a risk score.

Installation

1. Download the add-on zip from your GravityExtra account and upload it in Plugins → Add New → Upload Plugin, then activate it.
2. Go to Forms → Settings → hCaptcha, enter your key in the Gravity Extra License section and click Activate License.
3. Add your hCaptcha keys in the same screen (step 1), then add the field to your forms (step 3).

Step 1: Add Your hCaptcha Keys

1. Sign in to the hCaptcha dashboard. Under Sites, add your site (or open it) and copy its site key. It looks like four groups of letters and numbers separated by dashes.
2. Under Settings, copy your secret. It starts with 0x or ES_.
3. Paste both in WordPress and click Save Settings. The add-on asks hCaptcha whether the keys belong together before it saves them; a wrong secret or a site key from another account is refused with the reason.
4. Click Test the keys at any time. For a full check, click Show the widget, solve it, then click Test the keys: the add-on sends the real answer to hCaptcha and shows the result, including the host name where it was solved and, for Enterprise, the risk score.

The secret is never shown again after saving and never written to notes or logs. Leave the field empty to keep the saved secret.

Step 2: Choose the Checking Rules

The settings screen also shows the last problem the add-on met, such as a refused secret or a timeout, with the time it happened, so you notice a configuration issue before your visitors do.

Step 3: Add the hCaptcha Field to a Form

Open the form in the editor and click hCaptcha in Advanced Fields. Place it just above the submit button. A form can have one hCaptcha field; the editor refuses a second one.

Every setting can stay on Use the default, which follows the defaults in Forms → Settings → hCaptcha. The label, description, custom error message and CSS class work like on any Gravity Forms field. In invisible mode the label is hidden and the field shows the notice hCaptcha asks for: “This form is protected by hCaptcha and its Privacy Policy and Terms of Service apply.”

What Visitors See

• Checkbox mode: the visitor ticks the box (and solves a challenge if hCaptcha asks for one) and submits. Without a tick, the form says “Please confirm you are human with the hCaptcha check.”
• Invisible mode: the visitor just clicks Send. If they close a challenge, the form stays where it is and says the check was closed, so they can try again.
• Errors elsewhere: when another field has an error, the form comes back with “Verified by hCaptcha” instead of a new puzzle. The visitor only fixes the field.
• Expired answers: an answer is only valid for a short time. If it expires before submitting, the box clears and asks for a new tick.

Multi-page Forms, AJAX and Save and Continue

• Multi-page forms: put the field on the last page and the check runs when the form is submitted. Put it on an earlier page and the check runs when the visitor leaves that page; a signed pass, valid for 30 minutes and only once, carries the result to the final submit. A copied pass cannot be used for a second entry.
• AJAX forms: everything works without a page reload, including invisible mode and multi-page AJAX forms.
• Save and Continue: saving a draft never runs the check and never stores an hCaptcha answer in the draft. When the visitor comes back, the field shows a fresh widget.
• Several forms on one page: every hCaptcha field gets its own widget and only the submitted form is checked. The hCaptcha script is loaded once per page, so the language of the first form on the page is used.

The Result on Each Entry

Each entry stores the result as entry meta: hCaptcha (passed, or not checked when fail open let it through) and, for Enterprise accounts, hCaptcha risk score. Add them as columns in the entry list, filter by them or include them in exports. The note on the entry reads for example “hCaptcha: passed. Risk score 0.1 (limit 0.7). Reasons: safe.” The hCaptcha field itself saves no value, so it never appears in the entry fields, merge tags or exports.

Privacy: What Is Sent to hCaptcha

When a form is submitted, your server sends hCaptcha exactly four things: your secret, the answer token from the widget, your site key, and (if you allow it) the visitor’s IP address. Nothing the visitor typed into the form is ever sent. The widget itself is loaded from hCaptcha in the visitor’s browser, so mention hCaptcha in your privacy policy.

Working Next to Other CAPTCHA Fields

The hCaptcha script normally also answers to the name used by Google reCAPTCHA. The add-on turns that off, so the Gravity Forms reCAPTCHA field on another form of the same page keeps working with Google. Cloudflare Turnstile, for example in the GravityExtra Fraud Shield add-on, uses its own script and fields and is not affected.

Errors and What They Mean

For Developers

• gehc_skip_check (bool, form) skips the check for a submission, for example one made by your own code.
• gehc_load_api (bool, form) returns false when another plugin already loads the hCaptcha script on the page.
• The entry meta keys are gehc_result and gehc_score.

// Skip the check for submissions made by your own code through the Gravity Forms API.
add_filter( 'gehc_skip_check', function ( $skip, $form ) {
    return defined( 'MY_IMPORT_RUNNING' ) ? true : $skip;
}, 10, 2 );

// Another plugin already loads the hCaptcha script on this page.
add_filter( 'gehc_load_api', '__return_false' );

Troubleshooting