How to Integrate hCaptcha with MediaWiki

How do you integrate hCaptcha with MediaWiki?#

Load the hCaptcha module included with MediaWiki's ConfirmEdit extension, enter your hCaptcha sitekey and secret in LocalSettings.php, and choose which wiki actions should require verification. ConfirmEdit sends the submitted token from the MediaWiki server for validation and allows the protected action only after a successful response.

MediaWiki documents hCaptcha support in ConfirmEdit for MediaWiki 1.35 and later. Download the ConfirmEdit snapshot for the exact MediaWiki release you run: the project's master branch follows current development and is not backward compatible.

Reduce verification friction for wiki contributors#

• Ask less of legitimate participants. With hCaptcha Pro's 99.9% Passive mode, fewer than 0.1% of legitimate users receive a challenge on wiki actions selected in ConfirmEdit.
• Increase verification when activity looks suspicious. Pro adjusts challenge difficulty as risk rises, helping you keep participation less disruptive while applying stronger checks to higher-risk attempts.

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:

• MediaWiki 1.35 or later with server and LocalSettings.php access.
• A ConfirmEdit package matched to the installed MediaWiki release.
• An hCaptcha account that can create a sitekey and securely manage its matching secret.
• A list of actions and user groups that should encounter hCaptcha.

ConfirmEdit ships with MediaWiki release bundles, but it still requires configuration. Visit Special:Version on the wiki to confirm which extension version is active.

Create your hCaptcha credentials#

1. Start with hCaptcha Pro for fewer challenges and adaptive protection on wiki actions protected by ConfirmEdit, or use existing compatible hCaptcha credentials.
2. Create a sitekey for the MediaWiki hostname.
3. Add the production hostname and any separate staging hostname assigned to that sitekey.
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. Store the secret only in server-managed configuration with appropriately restricted access.

The sitekey is public and renders the widget. The secret authorizes server-side verification and must never appear in browser code or public wiki pages. We list MediaWiki in our integration catalog and integrations-list repository.

Install and configure ConfirmEdit#

Use the MediaWiki ConfirmEdit documentation or Extension Distributor to obtain the snapshot for the wiki's release. Developers can inspect the ConfirmEdit GitHub mirror or its canonical Gerrit repository.

Place the extension in the MediaWiki extensions/ConfirmEdit directory when it is not already bundled. Do not copy the current master branch into an older MediaWiki installation. After loading the extension, open Special:Version and confirm that ConfirmEdit appears.

Configure hCaptcha in LocalSettings.php#

Add the ConfirmEdit hCaptcha module and credentials. ConfirmEdit releases for MediaWiki 1.43 and later map the case-sensitive HCaptcha key to the extension class:

wfLoadExtensions([ 'ConfirmEdit', 'ConfirmEdit/hCaptcha' ]);
$wgCaptchaClass = 'HCaptcha';

$wgHCaptchaSiteKey = 'your-sitekey';
$wgHCaptchaSecretKey = 'your-secret';

Do not use 'hCaptcha' for $wgCaptchaClass. PHP array keys are case-sensitive, and ConfirmEdit's source maps 'HCaptcha' with a capital H. An unmatched value is treated as a class name and causes a class-not-found error.

For ConfirmEdit releases matched to MediaWiki 1.38 through 1.42, use the singular namespaced class:

$wgCaptchaClass = MediaWiki\Extension\ConfirmEdit\hCaptcha\HCaptcha::class;

ConfirmEdit releases matched to MediaWiki 1.35 through 1.37 use the older plural namespace:

$wgCaptchaClass = MediaWiki\Extensions\ConfirmEdit\hCaptcha\HCaptcha::class;

Use the configuration for the installed MediaWiki and ConfirmEdit branch. The namespaced class constant also remains a valid explicit option when that exact class exists in the matched release; do not copy a namespace from another release branch.

Keep the secret in a server-managed configuration path appropriate for the deployment. ConfirmEdit uses https://api.hcaptcha.com/siteverify by default and can optionally send the visitor's IP address when $wgHCaptchaSendRemoteIP is enabled.

Choose protected actions#

ConfirmEdit's defaults enable hCaptcha when someone adds an external URL, creates an account, or crosses failed-login thresholds. Every edit, new-page creation, and Special:EmailUser are disabled by default.

Set only the triggers the wiki needs:

$wgCaptchaTriggers['edit'] = false;
$wgCaptchaTriggers['create'] = false;
$wgCaptchaTriggers['sendemail'] = false;
$wgCaptchaTriggers['addurl'] = true;
$wgCaptchaTriggers['createaccount'] = true;
$wgCaptchaTriggers['badlogin'] = true;
$wgCaptchaTriggers['badloginperuser'] = true;

ConfirmEdit also supports namespace-specific trigger settings and a skipcaptcha permission. Its defaults allow registered bots and administrators to skip CAPTCHA while anonymous, registered, and autoconfirmed users do not receive that permission automatically. Review the effective permissions before launch.

MobileFrontend hCaptcha is disabled by default. If the wiki uses MobileFrontend, decide whether to enable $wgHCaptchaEnabledInMobileFrontend and test its editing and account workflows separately.

Verify the MediaWiki integration#

ConfirmEdit sends the submitted token to hCaptcha's siteverify endpoint from the MediaWiki server. Sitekey handling varies by ConfirmEdit release and account response: Enterprise responses may include a sitekey, while standard responses do not. Review the matched release’s expected-sitekey request and response checks; do not depend on a returned sitekey field for Pro verification.

1. Open each enabled workflow in a private browser window and confirm that hCaptcha appears when its trigger condition is met.
2. Complete hCaptcha and confirm that the account, edit, page, email, or login action finishes once.
3. Submit the same action without a valid response and confirm that MediaWiki blocks it.
4. Test users with and without skipcaptcha, including anonymous users, ordinary accounts, bots, and administrators as applicable.
5. Retest the desktop editor, VisualEditor, MobileFrontend, caches, Content Security Policy, and any AbuseFilter rule that invokes CAPTCHA.

Failed-login CAPTCHA triggers do not display an interactive challenge through API login. ConfirmEdit blocks the API login until the CAPTCHA requirement expires, so test browser and API authentication separately.

Troubleshoot common MediaWiki problems#

ConfirmEdit does not load

Check Special:Version, the extension directory, and the wfLoadExtensions call. Confirm that the extension snapshot matches the installed MediaWiki release.

hCaptcha does not appear

Confirm that the namespaced hCaptcha class is selected, both credentials are present, and the tested action meets an enabled trigger. Check whether the current user has skipcaptcha permission.

Every protected action fails

Confirm that the sitekey and secret belong to the same hCaptcha account and cover the active hostname. Check outbound server access to the configured verification URL and review MediaWiki logs without exposing the secret.

Desktop works but MobileFrontend does not

Confirm whether $wgHCaptchaEnabledInMobileFrontend is enabled. Test the active MediaWiki, ConfirmEdit, and MobileFrontend versions together before using it in production.

Choose Pro or discuss an Enterprise deployment#

hCaptcha Pro is the self-service path for MediaWiki. It includes 99.9% Passive mode, custom themes, more detailed analytics, and multi-user account access.

ConfirmEdit also exposes settings for Enterprise features such as risk scores, Secure Enclave, and health-check failover. Enable those only with the corresponding hCaptcha Enterprise configuration and a reviewed deployment plan.

FAQ#

Which MediaWiki versions support ConfirmEdit hCaptcha?

MediaWiki documents hCaptcha support beginning with version 1.35. Use the ConfirmEdit snapshot distributed for the installed MediaWiki release. The master branch follows current development and is not backward compatible.

Which actions can ConfirmEdit protect?

Its standard triggers cover edits, page creation, user email, adding URLs, account creation, and failed-login thresholds. Choose and test the triggers that match the wiki's abuse risks.

Does ConfirmEdit verify hCaptcha on the server?

Yes. It sends the response to the configured siteverify endpoint and rejects a protected action when verification fails.

Can trusted MediaWiki users skip hCaptcha?

Yes. ConfirmEdit provides the skipcaptcha permission. Review the effective group permissions carefully because the defaults differ for ordinary users, bots, and administrators.

Does hCaptcha work with MediaWiki MobileFrontend?

ConfirmEdit provides a MobileFrontend setting, but it is disabled by default. Enable it deliberately and test mobile editing and account workflows with the site's exact extension versions.