Gravity Forms reCAPTCHA - WordPress Plugin

Guide to Setting Up Gravity Forms reCAPTCHA to Protect WordPress Forms

Gravity Forms reCAPTCHA is not there to decorate a form or eliminate moderation altogether. Its real purpose is to quietly filter automated submissions in Gravity Forms. This guide covers add-on installation, connecting Google keys, choosing between reCAPTCHA v3 Classic, reCAPTCHA v3 Enterprise, and v2, configuring the risk threshold, reviewing entries, troubleshooting errors, and recognizing when a different anti-spam solution may be the better fit.

This article is intended for WordPress administrators who already use Gravity Forms and want to reduce junk submissions without creating unnecessary friction for real visitors. It does not cover buying a license or bypassing activation. The focus here is practical use of an already available product: where to find the settings, what the score means, why you should not guess the threshold, how to verify the results, and how to safely roll back questionable changes.

One important idea up front: reCAPTCHA v3 works differently from the familiar "I am not a robot" checkbox. In most cases, the user never sees a separate field. Instead, the system evaluates behavior and returns a score from 0 to 1. Gravity Forms stores that score with the entry and compares it to the threshold. So a solid Gravity Forms reCAPTCHA setup means more than just pasting in keys. You also need to know which forms actually need protection, which pages should not be broken by caching, where to review spam, and how to avoid blocking legitimate submissions.

What the Add-On Solves and Where Its Limits Are

The main job of Gravity Forms reCAPTCHA is to add Google reCAPTCHA v3 verification to Gravity Forms and use it as part of a broader anti-spam setup. In practice, this helps with contact forms, consultation requests, feedback forms, simple lead forms, registration flows, and other places that tend to attract automated submissions. For real users, the main advantage of v3 is that they usually do not have to solve a challenge, identify traffic lights in images, or click a checkbox.

The official product page emphasizes that this protection works in the background: reCAPTCHA v3 tracks interactions, returns a risk score, and submissions below the selected threshold are treated as spam. That makes it well suited for marketing forms where an extra step could hurt conversion rates. But this approach does require monitoring: if you set the threshold too aggressively, some legitimate submissions may also end up in spam.

Gravity Forms reCAPTCHA is not a firewall for your entire site. It does not replace admin login protection, a WAF, WordPress updates, SQL injection protection, attachment scanning, or a sound user role policy. The add-on only works in the context of Gravity Forms submissions. If spam is coming through WordPress comments, a third-party form, a REST endpoint from another plugin, or a custom handler, those issues need to be handled separately.

Who It Is a Good Fit For

This plugin is a strong choice for sites where Gravity Forms is already the main form builder and the administrator wants an official integration with clear support and results stored directly in entries. It is especially useful for service websites, agencies, educational projects, nonprofits, B2B landing pages, sites with request forms, and complex multi-page forms.

• The site receives a steady stream of junk submissions, but the owner does not want to complicate the form with a visible verification step for every visitor.
• The team wants to see the score or status directly in the Gravity Forms entries list instead of relying only on an external console.
• You need the ability to disable v3 for a specific form if it conflicts with another workflow or requires a different protection method.
• You need an official reCAPTCHA Enterprise integration, including OAuth connection and key selection from a Google Cloud Project.

When You Should Consider Another Option

If your site operates in a niche with strict privacy requirements and you are not comfortable sending behavioral signals to a Google service, look at Cloudflare Turnstile or another alternative. If the main issue is not bots but manual spam, meaningless submissions from real people, or low-quality ad leads, reCAPTCHA will do very little. And if the form is embedded on a heavily cached page where an optimizer constantly moves and defers JavaScript, you need to clean up caching and script loading first.

Practical rule of thumb: use Gravity Forms reCAPTCHA where you want to reduce automated spam while keeping the form submission experience smooth. Do not treat it as the only security measure for the entire site.

What to Check Before Installation

It is worth doing a quick round of prep before installation. It takes less time than troubleshooting "why did the form stop submitting?" later, and it helps you choose the right reCAPTCHA mode. For most sites, the prep comes down to four questions: which version of Gravity Forms is installed, where the keys will come from, how caching works on form pages, and whether the forms already contain older CAPTCHA fields.

Gravity Forms Version and Add-On Access

The reCAPTCHA Add-On documentation lists Gravity Forms 2.5 or later as a requirement, and the changelog later notes that newer add-on versions raised the minimum requirement to Gravity Forms 2.9.5. This article should not treat any specific version as a permanent constant, so the safest approach is simple: check the current requirements in the documentation and changelog before installing, then update both Gravity Forms and the add-on through the standard mechanism.

The add-on is available through the Gravity Forms ecosystem. You can install it from Forms > Add-Ons if your license includes access to official add-ons, or download the ZIP from your Gravity Forms account and install it through Plugins > Add New. Do not unzip the archive before uploading it through the WordPress admin area.

Google Keys and Domains

For reCAPTCHA v3 Classic, you need a Site Key and Secret Key from the Google reCAPTCHA Admin Console. For the Enterprise setup, you use Google Cloud Console, an Enterprise key, and an OAuth connection in Gravity Forms settings. Make sure the key is created for the exact domain where the form will run. It is best not to mix keys for a local environment, subdomain, and production domain, or your score and error diagnostics will become much harder to interpret.

There is a separate rule for v2: Checkbox and Invisible keys are not interchangeable. If you create a key for Checkbox but select Invisible in Gravity Forms, verification may fail. It sounds minor, but this kind of mistake often looks like "the keys are entered, but the form still complains."

Old CAPTCHA Fields in Forms

Pay especially close attention to forms where a CAPTCHA field was added manually in the past. Gravity Forms documentation explicitly warns that using a CAPTCHA field together with the reCAPTCHA Add-On can block form submission, display a blank CAPTCHA label, and trigger a verification error. With v3, you do not need to add a separate field in the form builder. The integration is applied automatically to all forms unless it is disabled in the settings for a specific form.

Caching, Script Optimization, and Form Pages

Gravity Forms depends on current JavaScript and dynamic form data. The Gravity Forms documentation separately warns that cached form pages, script combining, repeated minification, aggressive defer behavior, and Cloudflare Rocket Loader can break submissions. reCAPTCHA is especially sensitive to this: the token has to be obtained and submitted at the right time, and Google notes that v3 tokens have a short lifespan and should be executed close to the user action.

Before enabling it on a live site, exclude pages with important forms from page cache and verify that Gravity Forms and reCAPTCHA scripts are not being deferred by your optimizer. That does not mean the site has to become slow. It means a dynamic form should not be served like a static image from cache.

Installing and Connecting Gravity Forms reCAPTCHA for the First Time

Installation has two parts: first you activate the add-on, then you connect the keys and choose the connection type. Do not start by changing the threshold. First make sure the Google connection works, the keys are valid, and the form submits normally without errors.

Installing Through the Add-Ons Browser

The easiest route is to open Forms > Add-Ons in the WordPress admin area, find the reCAPTCHA Add-On, click Install, and then Activate Plugin. After activation, check whether the reCAPTCHA settings page appears. If it does not, first confirm that Gravity Forms is active, the add-on was not disabled because of an error, and the current user has sufficient administrator permissions.

Installing from a ZIP File

If you are installing the add-on manually, download the ZIP from your Gravity Forms account, then open Plugins > Add New, click Upload Plugin, select the ZIP, and install it the standard WordPress way. After installation, click Activate Plugin. Leave the FTP method as a fallback for cases where the normal admin upload is unavailable.

Where the Settings Are Located

The main settings path is Forms > Settings > reCAPTCHA. That is where you choose the connection type: reCAPTCHA v3 Enterprise, reCAPTCHA v3 Classic, or v2. Gravity Forms documentation notes that v3 settings appear only when the reCAPTCHA Add-On is installed, while v2 is historically tied to the CAPTCHA field and support built into the Gravity Forms core.

For v3 Classic, paste the Site Key and Secret Key into the appropriate fields. If the keys are valid, Gravity Forms shows green indicators next to them. For Enterprise, choose the Enterprise connection type, complete the OAuth flow, select the Google Cloud Project, and then choose the required Enterprise key. If your Google Workspace organization requires periodic reauthorization, the connection may ask for reauthentication later. That is normal Workspace policy, not necessarily a plugin error.

Initial Verification After Saving

After saving the settings, do not test the form only through preview. Gravity Forms documentation states that reCAPTCHA does not process submissions from form preview. Create or open a real WordPress page where the form is published through a block, shortcode, or another standard output method. Submit a test entry as a normal visitor, then open the form entries and check whether the entry appears, what its status is, and whether the reCAPTCHA score or status is shown.

Quick check: if the entry is created, the notification is sent, and a score appears in Entries, the basic connection is working. If no score appears, check the key type, connection status, form settings, and page caching.

How Score, Threshold, and Spam Classification Work

The most important part of the setup is understanding the relationship between score and threshold. Google reCAPTCHA v3 returns a score from 0 to 1: the closer the value is to 1, the more likely the interaction is legitimate; the closer it is to 0, the higher the bot risk. Gravity Forms compares that score to the threshold defined in settings. If the score is less than or equal to the threshold, the entry is classified as spam.

Why 0.5 Is Usually a Better Starting Point Than 0.9

Gravity Forms lists 0.5 as the default threshold, and its troubleshooting documentation warns that at 0.9 and above, most or nearly all submissions may be marked as spam. That does not mean 0.5 is perfect for every site. It means starting with an extremely high threshold is risky. First collect some real submissions, compare the scores of legitimate entries and junk entries, and then adjust the threshold gradually.

There is another important nuance: v3 learns from real traffic. Google explicitly states that scores in a test environment or immediately after deployment may differ from production. So do not draw conclusions from a single test submission made by an administrator who is already logged in to WordPress and visits the site unusually often. You need realistic conditions: a normal browser, an incognito window, mobile traffic, the form on a published page, and at least a short observation period.

What Happens to Feeds, Notifications, and Confirmations

When an entry is marked as spam during submission by a compatible anti-spam method, Gravity Forms does not process the configured feeds, notifications, or confirmations for that entry. This matters for submissions that are supposed to go to a CRM, email marketing platform, Help Scout, Slack, or another service. If a legitimate entry was incorrectly sent to spam, you can restore it to Not Spam, but the automatic workflow does not always replay everything exactly as it would during a normal submission. The documentation specifically notes that when an entry is moved to Not Spam, add-on feeds may be processed except payment add-on feeds, while notifications are not sent automatically and must be resent manually.

How to Read Statuses Instead of Scores

Sometimes you will see a status instead of a number. Gravity Forms documentation lists states such as disabled, disconnected, disconnected (reauthentication required), disabled (quota limit), disabled (token refresh in progress), and disabled (token refresh failed). These indicate the state of the configuration or service, not the quality of the visitor. For example, disabled may mean reCAPTCHA is turned off in that form's settings, while disconnected may mean there are no valid v3 keys or the Enterprise connection is not authorized.

Do not try to fix a status by changing the threshold. If the status points to a disconnect, quota issue, or refresh problem, first restore the keys, OAuth connection, quotas, or Google Workspace access. The threshold affects how scores are classified, but it does not fix a missing score.

Choosing Between v3 Classic, v3 Enterprise, and v2

Gravity Forms reCAPTCHA supports several scenarios, and the mode you choose affects how the form behaves. You cannot reduce the decision to "v3 is newer, so it must be better." On a site with simple contact forms, v3 Classic may be more than enough. On a project with a corporate Google Cloud policy, heavy traffic, and stricter key management requirements, Enterprise makes more sense. And if you need a visible checkbox, you need v2 or an Enterprise key with the checkbox challenge type.

reCAPTCHA v3 Classic

This mode works well for most standard WordPress sites that need background risk scoring without a visible field. The administrator creates v3 keys in Google reCAPTCHA Admin Console, enters the Site Key and Secret Key in Gravity Forms, and the add-on automatically applies verification to the forms. There are not many extra settings for v3 Classic: keys, threshold, and the option to hide the badge if you meet Google's requirements.

The advantage of v3 Classic is simplicity. The downside is fewer enterprise-grade tools and a stronger dependency on scripts working correctly on form pages. If your forms are business-critical, complement the setup with regular review of spam entries and logs.

reCAPTCHA v3 Enterprise

The Enterprise setup uses a Google Cloud Project, OAuth, and Enterprise keys. It is useful when the site is managed by a team that needs keys, quotas, reauthentication, and access controls handled through Google Cloud. The Gravity Forms changelog shows that the add-on has actively expanded the Enterprise side of the product: support was added for the Enterprise API, the checkbox type for Enterprise keys, and improved handling of token refresh and disconnected statuses.

Enterprise should not be enabled just because the word sounds more serious. It makes sense when you already have a Google Cloud workflow, organizational requirements, or a higher risk of abuse. For a small site without a Google Cloud administrator, it may be more complexity than you actually need.

reCAPTCHA v2 and the CAPTCHA Field

v2 is still the right option when you need a visible challenge. Gravity Forms supports v2 Checkbox and Invisible, and v2 does not require the reCAPTCHA Add-On in the same way v3 does. With v2, you can use the CAPTCHA field. But v2 introduces more visible friction, especially on mobile devices and in long forms. That is why v2 is best used when users are prepared for verification and the cost of a junk submission is higher than a slight decline in UX.

Practical Example: Protecting a Lead Form Without Adding Friction

Let us look at a typical scenario: an agency website has a form called "Get a Consultation." It includes name, email, phone, subject, and message. Spam comes in regularly, but the site owner does not want to add a visible checkbox because the form is used in advertising and fast submission matters. The goal is to enable reCAPTCHA v3, keep the submission flow smooth, and learn how to review questionable entries.

Goal and Preparation

The goal is for the form to accept legitimate leads while sending suspicious submissions to spam entries. Before you begin, Gravity Forms and the reCAPTCHA Add-On should already be installed, the form should be created, and a page with that form should be published. The form page should be excluded from cache, or at least temporarily tested without page cache and aggressive script optimization.

Setup Steps

1. Open Google reCAPTCHA Admin Console and create v3 keys for the site's domain.
2. In WordPress, go to Forms > Settings > reCAPTCHA.
3. Select the connection type for v3 Classic and paste in the Site Key and Secret Key.
4. Save the settings and make sure valid indicators appear next to the keys.
5. Leave the threshold at the starting value of 0.5 if you do not yet have site-specific statistics.
6. Open the form in the editor and make sure it does not still contain an old CAPTCHA field if you are using v3.
7. Publish or update the page, then submit a test lead from the normal public page, not from preview.
8. Open Forms > Entries, find the entry, and review the reCAPTCHA score or status.

Checking the Result

After the test submission, do not rely only on the "form submitted" message. Open the entry itself. If a score is present, the add-on requested an evaluation. If the entry went to spam, open its detail page and read the note: in newer add-on versions, the reCAPTCHA note may include the score and threshold that caused the entry to be treated as spam. That is much more useful than guessing from the general status.

Then ask one more person to submit a real test lead from a different device or network. If both legitimate submissions score comfortably above the threshold, keep the settings and continue observing. If legitimate submissions receive low scores, do not rush to disable everything. Check caching, script optimization, Google regional restrictions, browser extensions, and the submission flow first, and only then consider lowering the threshold.

A Note on Multi-Page Forms

The documentation states that the add-on works with multi-page forms, but you may still see log messages about verification being skipped on pages other than the first or last. That does not mean the plugin is broken. What matters is testing the final submission, not just transitions between form pages. For long forms, also keep token lifespan in mind: if a user spends a long time filling out the form, the behavior may differ from a quick test submission by an administrator.

Reviewing Entries, the Spam Filter, and Post-Submission Behavior

One of the strongest parts of the integration is that you can review results in the familiar Gravity Forms interface. You do not have to open Google Console every time you want to understand why a specific submission was marked as spam. The Entries List and Entry Detail screens may display the score, status, notes, and actions such as Spam or Not Spam.

Where to Look for Missing Leads

If a client says they submitted the form but no email arrived, the first place to check is not the inbox, but Entries. The entries page includes a Spam filter. Entries marked as spam may not trigger notifications or feeds, so the email may have failed to send because the filter intercepted it. Open the spam entry and review the note. If it mentions reCAPTCHA and a score below the threshold, the cause is clear. If the note points to Honeypot, Akismet, Zero Spam, or another filter, then that specific tool needs to be investigated.

How to Use Mark as Not Spam

If the entry is legitimate, you can restore it from spam. For Enterprise connections, Gravity Forms describes an extra benefit: marking an entry as not spam tells Google about the false positive and helps improve scoring. But do not turn that into your only process. If real leads are consistently ending up in spam, the problem is not one entry. You need to review the threshold, caching, script conflicts, key type, and the conditions under which the form is being filled out.

When to Enable Logging

Logs are not always necessary. Turn them on when you see a disconnected status, token verification errors, unclear false positives, a caching conflict, or a problem that cannot be reproduced from normal entries alone. In Gravity Forms, logging is enabled in settings, after which the Logging section becomes available. The documentation warns that logs may contain sensitive and personal data, so they should not be left enabled permanently. Once the investigation is finished, disable logging and delete old logs.

Safe habit: enable logs only for the duration of troubleshooting, do not publish them publicly, and do not send them to third parties without removing personal data first.

Privacy, the Badge, and Compatibility with Optimization

reCAPTCHA is a Google service. Gravity Forms documentation explicitly reminds users that using the service requires sending information about user behavior to Google pages for evaluation. In practical terms, that creates two tasks for the site owner: clearly present the required privacy messaging to users and avoid breaking the badge or scripts through optimization.

Can You Hide the Badge?

The reCAPTCHA Add-On settings include a Disable Google reCAPTCHA Badge option. It hides the badge that normally appears on pages. But Gravity Forms points to Google's terms: you can hide the badge only if you follow Google's requirements, including visible disclosure about reCAPTCHA protection in the user flow. So do not enable that option just because the badge interferes with the design. First add the correct disclosure near the form or submission area, review your privacy policy, and make sure the designer has not hidden the notice in the responsive layout.

Why Caching Breaks Forms More Often Than It Seems

Cache is useful for static pages, but forms are a dynamic interface. Gravity Forms explains that caching and script optimization can inject stale nonces, break script dependencies, minify already prepared JavaScript a second time, or defer code that must run before submission. With reCAPTCHA, this may show up as a missing token, a status instead of a score, failed submission, a blank CAPTCHA label, or inconsistent results from the same actions.

The practical rule is simple: pages with critical forms should be excluded from page cache, and Gravity Forms and reCAPTCHA scripts should not be subjected to aggressive combine or defer behavior without testing. If your optimizer supports excluding specific URLs and scripts, use those exclusions. If it does not, disable the relevant feature on form pages.

A Careful CSS Adjustment for v2 Checkbox

With v3, you usually do not need to style a separate field. But if you are using v2 Checkbox, the widget may need slightly better spacing in your theme. Gravity Forms documentation on CAPTCHA field CSS selectors shows that in the Orbital theme, you can target the .gfield--type-captcha and .ginput_recaptcha containers. Below is a small adjustment that is safe to add to custom theme CSS or a snippets plugin. It does not change verification logic. It only improves spacing and the border around the visible v2 field.

/* Gravity Forms v2 CAPTCHA field: visual spacing only */
.gform-theme--framework .gfield--type-captcha {
  padding: 10px 0;
  border: 1px solid #e5e7eb;
  border-radius: 6px;
}

.gform-theme--framework .gfield--type-captcha .ginput_recaptcha {
  margin-top: 6px;
}

Check the result on a mobile screen and in a browser where you are not logged in. If the checkbox becomes clipped, conflicts with the container width, or the theme already applies its own styles, roll the CSS back. Do not radically change iframe dimensions: reCAPTCHA embeds third-party markup, and overly aggressive styling can hurt accessibility.

Common Problems and Troubleshooting

Troubleshooting works best when you move from the visible symptom to the actual cause. Do not start by reinstalling the add-on. In most cases, it is enough to check the status in Entries, the key settings, old CAPTCHA fields, caching, logs, and the threshold.

The form shows a CAPTCHA error or a blank CAPTCHA label

Symptom: the user tries to submit the form but sees a verification error, a blank CAPTCHA label, or the form fails validation. Possible cause: the form still contains an old CAPTCHA field while the reCAPTCHA Add-On with v3 is already enabled globally. Gravity Forms warns that this combination can block submission.

What to check: open the form in the editor and look for a CAPTCHA field. If you are using v3, remove the field from the form or disable reCAPTCHA v3 for that specific form in Form Settings. How to fix it: for v3, keep the automatic integration without a field. For v2, use the CAPTCHA field and the matching key type. When to roll back: if removing the field removes a visible verification step you still need, switch back to v2 Checkbox and disable v3 for that form.

Entries show disconnected instead of a score

Symptom: the entry is created, but the score column shows the status disconnected. Possible cause: valid v3 Site Key and Secret Key were not saved, the Enterprise connection is broken, the OAuth token expired, or Google Workspace requires reauthentication.

What to check: open Forms > Settings > reCAPTCHA, confirm that the correct connection type is selected, the keys match the domain, and the Enterprise project and key are available. In a Workspace environment, ask the administrator whether the app needs to be trusted or whether the reauthentication policy must be changed. How to fix it: save the keys again, repeat the OAuth flow, or choose the correct Enterprise key. When to roll back: if the Enterprise connection keeps resetting because of organizational policy, temporarily switch to Classic or another anti-spam method until the Google Workspace administrator configures trust correctly.

Legitimate leads are being sent to spam

Symptom: a client says they submitted the form, but no email arrived and the lead is sitting in the Spam tab. Possible cause: the score is below or equal to the threshold, the threshold is too high, the site has not yet developed a normal v3 traffic profile, the visitor used an unusual environment, or the filter that fired was not reCAPTCHA at all.

What to check: open Entry Detail and read the spam filter note. If the note points to reCAPTCHA, compare the score and threshold. If the threshold is 0.9 or higher, lower it closer to the usual starting point and observe. If the note points to Honeypot, Akismet, or Zero Spam, review the settings for that filter instead. How to fix it: adjust the threshold gradually, verify caching and scripts, and mark legitimate entries as Not Spam. When to roll back: if the form is business-critical and false positives continue, temporarily disable v3 for that specific form and use v2 Checkbox, Turnstile, or manual moderation instead.

The score does not appear in form preview

Symptom: the administrator tests the form through preview and does not see a reCAPTCHA result. Cause: Gravity Forms states that reCAPTCHA does not process submissions from form preview. What to check: publish the form on a real page and submit the test from there. How to fix it: use a public test page blocked from indexing if you do not want users to see the form before verification.

The form behaves inconsistently after caching is enabled

Symptom: sometimes the form submits, sometimes it returns a validation error, and the logs mention a missing token, stale data, or script-related issues. Possible cause: page cache, CDN, script combine, minify, defer, or Rocket Loader is serving an outdated form or disrupting the JavaScript load order.

What to check: temporarily disable caching and script optimization, clear the site cache and browser cache, and run the test again. Check network headers: cf-cache-status, x-cache, x-kinsta-cache, and similar values can tell you whether the page was served from cache. How to fix it: exclude form pages and Gravity Forms or reCAPTCHA scripts from the relevant optimizers. When to roll back: if the optimizer cannot reliably exclude dynamic forms, disable the problematic feature on pages with forms.

A quota limit or token refresh failed status appears

Symptom: the status shows disabled (quota limit) or disabled (token refresh failed). Possible cause: reCAPTCHA API limits, a problem with Enterprise token refresh, or a temporary connectivity failure. Google documents reCAPTCHA limits and the conditions for moving to Enterprise at higher volume, while Gravity Forms exposes separate statuses for quota and refresh issues.

What to check: open Google Console and review request volume, key health, and the Enterprise project state. In Gravity Forms, enable logging only for the duration of the investigation. How to fix it: restore the token, review quotas, and discuss an Enterprise setup if needed. When to roll back: if the service is unavailable during a critical period, temporarily use another anti-spam method and do not raise the threshold as a "fix" for quota issues.

When Gravity Forms reCAPTCHA Is the Right Choice

Gravity Forms reCAPTCHA is worth using if you need an official reCAPTCHA integration for Gravity Forms, background v3 protection without an extra step for the visitor, and a clear way to review scores inside Entries. It is especially useful for sites where forms are already part of existing workflows: leads go to a CRM, emails, notifications, support tools, or internal processing.

Before going live, check four things: valid keys for the correct domain, no leftover CAPTCHA field when using v3, form pages excluded from aggressive caching, and a successful test submission on a published page. Then monitor spam entries, avoid raising the threshold without data, and use logs only while troubleshooting.

If the setup fits your scenario after testing, you can get the WordPress version and move on to careful testing on your own form. Start with one important but not mission-critical form, collect the first scores, review real submissions, and only then roll the configuration out to the rest of the site's forms.