Mautic Multi-CAPTCHA Plugin

This project has been pruned to only support Mautic 6 and Mautic 7. You can use it with Mautic 5 as well, but we do not officially support this.

This plugin is offered by FireMultimedia. Would you like to use Mautic worry-free, with built-in extra features like this plugin? Get in touch with us at https://www.firemultimedia.nl/mautic-hosting/.

Supported CAPTCHA Solutions

This bundle provides five CAPTCHA options to protect your Mautic forms:

• ALTCHA: Self-hosted, GDPR-compliant CAPTCHA with no external dependencies (recommended for privacy-sensitive applications)
• hCaptcha: Privacy-focused alternative to reCAPTCHA with accessibility features
• Google reCAPTCHA: Industry-standard CAPTCHA with v2 (checkbox) and v3 (invisible scoring) options
• Cloudflare Turnstile: Modern, privacy-respecting CAPTCHA from Cloudflare
• Cap: Self-hosted proof-of-work CAPTCHA (with combined bot/instrumentation detection) - requires your own Cap Standalone instance

Installation

1. Execute composer require firemultimedia/mautic-multi-captcha-bundle in the main directory of the mautic installation
2. flush the cache php bin/console cache:clear.
3. Navigate to the Plugins page and click "Install/Upgrade Plugins".

You should now see five new plug-ins: ALTCHA, hCaptcha, Google reCAPTCHA, Cloudflare Turnstile, and Cap.

Configuration

ALTCHA

ALTCHA is designed with privacy in mind and offers significant advantages for GDPR compliance:

• No External API Calls: All challenge generation and validation happens locally on your server
• No Third-Party Scripts: The widget can be loaded from your own server or a CDN without tracking
• No Cookies or Storage: ALTCHA does not use cookies or browser storage
• No User Data Collection: No personal data is collected or transmitted to third parties
• No Explicit Consent Required: Since no external services are used, explicit consent is not necessary under GDPR

This makes ALTCHA an ideal choice for organizations that need to comply with strict data protection regulations while still protecting their forms from spam and abuse. Because of this, it requires slightly different (manual) configuration than the other solutions.

Generate a secure random string to use as your (Hash-based Message Authentication Code) HMAC key. You can copy the output of the following (bash) command:

openssl rand -hex 32

Paste it here, alongside the proof-of-work complexity settings - these are configured once, globally, under the ALTCHA integration (not per-field), since a challenge endpoint can't be given a reference to a specific form field without weakening its security:

• Hash Algorithm (SHA-1 / SHA-256 / SHA-512, default: SHA-256): Which hash algorithm the proof-of-work challenge uses. SHA-512 requires more computation per attempt than SHA-256, further increasing difficulty.
• Max Number (1000-100000000, default: 1000000): Controls the difficulty of the challenge. Higher numbers make the challenge harder to solve but take longer.
• Challenge Expires (10-600 seconds, default: 180): How long the challenge remains valid before expiring. Increase this if a higher Max Number causes challenges to expire before they can be solved.

The ALTCHA field itself, on the "Properties" tab of the form, only exposes:

• Invisible Mode (default: off): When enabled, the CAPTCHA widget is hidden and automatically solves the challenge in the background without user interaction.

ALTCHA supports an invisible mode where the challenge is solved automatically in the background without displaying a visible widget to the user. This provides a seamless user experience while still protecting against spam.

To enable invisible mode:

1. Edit the ALTCHA field properties in your form
2. Toggle "Invisible Mode" to "Yes"
3. Save the form

When invisible mode is enabled, the challenge is solved automatically when the form loads, and users can submit the form without any additional interaction.

Cross-Origin Resource Sharing (CORS): see ALTCHA-CORS.md

API Endpoint

The plugin provides a REST API endpoint for dynamic challenge generation, which solves caching issues in Mautic forms:

Endpoint: GET /altcha/api/challenge

Parameters: None. The endpoint always reads maxNumber, expires and algorithm from the global ALTCHA integration settings described above, falling back to 1000000 / 180 / SHA-256 if the integration isn't configured yet.

Example Request:

curl "https://your-mautic.com/altcha/api/challenge"

Example Response:

{
    "algorithm": "SHA-256",
    "challenge": "abc123...",
    "maxnumber": 1000000,
    "salt": "def456...",
    "signature": "ghi789..."
}

This API endpoint is automatically used by the Altcha widget via the challengeurl attribute to ensure fresh challenges are generated for each form load, preventing caching issues. The widget handles all the complexity internally - no custom JavaScript required.

hCaptcha

Collect your keys from hCaptcha and place them here:

The hCaptcha field in the Mautic form can be configured under the "Properties" tab.

Google reCAPTCHA

Collect your keys from Google reCAPTCHA and place them here:

The Google reCAPTCHA field in the Mautic form can be configured under the "Properties" tab. Google reCAPTCHA will rank traffic and interactions based on a score of 0.0 to 1.0, with a 1.0 being a good interaction and scores closer to 0.0 indicating a good likelihood that the traffic was generated by bots.

Cloudflare Turnstile

Collect your keys from the Cloudflare dasboard (under Turnstile -> Add widget) and place them here:

The Cloudflare Turnstile field in the Mautic form can be configured under the "Properties" tab.

Cap

Cap combines a SHA-256 proof-of-work challenge with instrumentation/bot detection - both always run together, there is no way (nor a need) to enable just one.

This integration only supports a self-hosted Cap Standalone instance. There is no Cap Cloud/API-key mode. The Mautic plugin never talks to that instance directly for challenge solving - the visitor's browser does, via the widget - Mautic only performs the final server-to-server /siteverify call using your secret key.

1. Deploy your own Cap Standalone instance (Docker/npm, see the Cap docs) and create a site key on it.
2. Configure the difficulty (proof-of-work difficulty, instrumentation, headless-browser blocking, etc.) on that Cap Standalone instance's own dashboard - none of that is configured in Mautic.
3. In Mautic, open the Cap integration and fill in:
   • Server URL: base URL of your Cap Standalone instance, e.g. https://cap.example.com
   • Site Key
   • Secret Key

The Cap field has one field-level option, Solve Mode, on the "Properties" tab (there's no cookie-consent gate to configure, since the widget talks to your own server, not a third party):

• Manual (default): the visitor clicks the checkbox themselves.
• Auto-solve (widget stays visible): the widget solves itself as soon as it loads, no click needed, but the checkbox and Cap's branding link are still shown.
• Auto-solve (widget hidden): same as above, but the entire widget is hidden. This is the only mode without a visible branding link - Cap's own anti-tamper logic actively restores its branding/credits link whenever the widget itself is visible, so hiding just the link while keeping the checkbox visible isn't possible.

The "General" tab only has the generic label/help-text/save-result fields every Mautic field type exposes:

CORS: unlike ALTCHA's widget script (loaded as an ES6 module, see ALTCHA-CORS.md), Cap's widget script loads as a plain <script> and needs no CORS headers. Its WASM proof-of-work solver, however, is fetched via fetch(), which does enforce CORS - this plugin already serves that WASM file through its own route (/cap/api/wasm) with the required Access-Control-Allow-Origin header, so no manual web-server configuration is needed even when your forms are embedded on a different domain than Mautic.

Usage in Mautic Form

ALTCHA

Add the "ALTCHA" field to the form and save changes.

Note: Unlike other CAPTCHA solutions, ALTCHA does not require explicit consent mode because it does not use external services or collect user data. All processing happens locally on your server. In standard mode, users see a checkbox-style widget. In invisible mode, the challenge is solved in the background without any visible widget.

Explicit consent mode:	Invisible mode:

hCaptcha

Add the "hCaptcha" field to the form and save changes.

Explicit consent mode:	Implicit consent mode:

Google reCAPTCHA v2

Add the "Google reCAPTCHA" field to the form and save changes.

Explicit consent mode:	Implicit consent mode:

Google reCAPTCHA v3

Add the "Google reCAPTCHA" field to the form and save changes.

Explicit consent mode:	Implicit consent mode:

Cloudflare Turnstile

Add the "Cloudflare Turnstile" field to the form and save changes.

Explicit consent mode:	Implicit consent mode:

Cap

Add the "Cap" field to the form and save changes. There is only one mode - the widget always runs both challenge components together.

Acknowledgements

• Original code by Konstantin Scheumann
• ALTCHA and Cap integration by Björn Rafreider