How to Integrate hCaptcha with Craft Freeform

How do you integrate hCaptcha with Craft Freeform?#

Create an hCaptcha sitekey and secret, add Freeform's native hCaptcha integration under Freeform > Integrations, choose Checkbox or Invisible mode, and enable the integration on every form that needs protection. Freeform renders and validates hCaptcha as part of its submission workflow, so this setup does not require the separate Craft hCaptcha plugin.

Freeform 5 supports Craft 4, Craft 5, and Craft Cloud. Captcha integrations are available across all Freeform editions in Freeform 5.9 and later.

These instructions were last validated on September 16, 2026 with Solspace Freeform 5.15.29.

Make Freeform submissions less disruptive#

• Keep attention on the submission. hCaptcha Pro's 99.9% Passive mode challenges fewer than 0.1% of legitimate users, reducing interruptions for people completing Freeform forms with the native hCaptcha integration enabled.
• Give suspicious activity more scrutiny. Pro adapts challenge difficulty to risk, helping you balance an easier form experience for legitimate visitors with stronger checks against automated abuse.

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:

• A Craft CMS site running a compatible Freeform 5 release.
• Permission to manage Freeform integrations and edit each protected form.
• An hCaptcha account that can create a sitekey and securely manage its matching secret.
• A publicly accessible hostname covered by the sitekey.

The sitekey is sent to the browser so hCaptcha can run. The secret authenticates verification and must remain private. Store credentials through your deployment's approved secret-management process and limit access to administrators who configure the integration.

Check the current Freeform Plugin Store page, Freeform documentation, and Solspace source repository before changing versions.

Create your hCaptcha credentials#

1. Start with hCaptcha Pro for fewer challenges and adaptive protection on Freeform submissions, or use existing compatible hCaptcha credentials.
2. Create a sitekey in the hCaptcha dashboard.
3. Add every production hostname that will display a protected Freeform form.
4. 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.
5. Keep the secret in the server-side configuration path approved for the Craft deployment.

Use separate sitekeys when staging and production need independent behavior or reporting. The hCaptcha integration catalog lists Freeform under Craft CMS, and the hCaptcha integrations repository provides the broader integration index.

Configure hCaptcha in Freeform#

1. In the Craft control panel, open Freeform > Integrations.
2. Find hCaptcha in the Captchas section and create or open the integration.
3. Choose hCaptcha Checkbox or hCaptcha Invisible.
4. Enter the sitekey and secret from the hCaptcha dashboard.
5. Decide whether Freeform should delay loading captcha scripts until a visitor interacts with the form.
6. Choose Display Error Message or Send to Spam Folder for failed checks. Add a custom message if you display errors.
7. For Checkbox mode, choose the default Light or Dark theme and Normal or Compact size.
8. Save the integration.

These settings provide defaults. They do not protect every Freeform form automatically.

Enable hCaptcha on each form#

1. Open a form in the Freeform form builder.
2. Select the Integrations tab.
3. Select the hCaptcha integration.
4. Enable it for the form and adjust any form-specific settings.
5. Save the form and repeat these steps for each form that should use hCaptcha.

With Checkbox mode, Freeform inserts the field above the form's submit button by default. Freeform 5.7 and later also support manual captcha placement when a custom template needs another position. Invisible mode runs during submission and can present a challenge when required.

Do not deploy a template with Freeform's disableCaptcha: true query parameter on a protected form. That override disables captcha for the rendered form.

Choose the failure behavior#

Display Error Message rejects the attempt visibly and helps during controlled troubleshooting. Send to Spam Folder follows Freeform's spam workflow. When the Spam Folder is enabled, Freeform stores the submission as spam and suppresses its email notifications and API integrations. Approving the submission later triggers those queued actions.

Select the behavior that matches how form owners review submissions and downstream actions. Document the choice so support staff know whether a rejected test should show an error or appear in Freeform's Spam Folder.

Verify the Freeform integration#

Test every protected form on its public route.

1. Open the form in a private browser window and confirm that Checkbox mode appears or Invisible mode initializes.
2. Complete hCaptcha and submit valid data. Confirm that Freeform accepts the submission once and runs the expected notification or integration.
3. Submit without a valid hCaptcha result. Confirm that Freeform follows the configured failure behavior and does not treat the attempt as a normal submission.
4. If the Spam Folder is enabled, confirm that notifications and API integrations stay suppressed until the item is approved.
5. Retest AJAX and multi-page forms, along with the site's Content Security Policy, cache, consent manager, and custom formatting template.

Troubleshoot common Freeform problems#

hCaptcha does not appear on a form

Confirm that the global hCaptcha integration is saved and enabled in that form's Integrations tab. Check that the current hostname belongs to the sitekey. If scripts load after interaction, click or focus the form and review the browser console and Content Security Policy reports.

hCaptcha appears on some forms only

Freeform enables the integration per form. Open every affected form and inspect its Integrations tab. Also check custom template code for disableCaptcha: true.

Valid submissions are treated as spam

Confirm that the sitekey and secret belong to the same hCaptcha account and cover the active hostname. Review the spam reason stored by Freeform, then use Display Error Message temporarily in a controlled environment when a visible failure helps isolate the problem.

The checkbox is in the wrong position

Freeform normally inserts it above the submit button. Use Freeform's documented manual captcha placement for version 5.7 or later when a custom formatting template needs a different position. Retest the form after changing its template.

Choose Pro or discuss an Enterprise deployment#

hCaptcha Pro is the self-service path for a Freeform deployment. It includes 99.9% Passive mode, custom themes, more detailed analytics, and multi-user account access. After changing sitekey behavior, test accepted and rejected submissions again.

Organizations with higher-volume forms, risk-score workflows, custom threat models, centralized access requirements, or contractual service needs should plan the deployment with our team. Review the Freeform failure path, credential ownership, Spam Folder workflow, downstream integrations, and rollout across every Craft site.

FAQ#

Does Freeform include hCaptcha support?

Yes. Freeform 5 includes a native hCaptcha integration with Checkbox and Invisible options. Beginning with Freeform 5.9, captcha integrations are available in all Freeform editions.

Do I need the separate Craft hCaptcha plugin for Freeform?

No. Freeform has its own native integration and submission handling. Use the separate Craft plugin for supported Craft Contact Form, registration, or custom-form workflows outside Freeform.

Does enabling hCaptcha globally protect every Freeform form?

No. After configuring the integration under Freeform settings, enable it separately in each form's Integrations tab.

What happens when a Freeform hCaptcha check fails?

Freeform can display an error or send the submission to its Spam Folder. With the Spam Folder enabled, notifications and API integrations remain suppressed until an administrator approves the submission.

Can Freeform use invisible hCaptcha?

Yes. Select the Invisible type in the hCaptcha integration, enable it on the form, and test the full public submission flow. A challenge can still appear when required.