Skip to Content

Migrate from hCaptcha

hCaptcha and CaptchaFox are integrated the same way, so most changes are renames.

Get your CaptchaFox keys

Create a site in the CaptchaFox portal and copy its sitekey and secret key. Your hCaptcha keys won’t work with CaptchaFox.

Update client-side code

Replace the script tag

<script src="https://js.hcaptcha.com/1/api.js" async defer></script>

becomes

<script src="https://cdn.captchafox.com/api.js" async defer></script>

Query parameter hl becomes lang.

Update the container element

<div class="h-captcha" data-sitekey="HCAPTCHA_SITEKEY"></div>

becomes

<div class="captchafox" data-sitekey="YOUR_SITEKEY"></div>

Invisible hCaptcha: data-size="invisible" becomes data-mode="hidden". See Hidden Mode.

Update JavaScript API calls

Only if you use the JavaScript API:

const id = hcaptcha.render('container', { sitekey: 'HCAPTCHA_SITEKEY', callback: handleVerify, 'expired-callback': handleExpire, 'error-callback': handleError, 'close-callback': handleClose, }); hcaptcha.getResponse(id); hcaptcha.reset(id); const { response } = await hcaptcha.execute(id, { async: true });

becomes

const id = captchafox.render('container', { sitekey: 'YOUR_SITEKEY', onVerify: handleVerify, onExpire: handleExpire, onError: handleError, onClose: handleClose, }); captchafox.getResponse(id); captchafox.reset(id); const token = await captchafox.execute(id); // resolves with the token

Update server-side code

Read the token from the new form field and send it to the CaptchaFox endpoint, with the secret key of your CaptchaFox site:

curl https://api.hcaptcha.com/siteverify \ -d secret=HCAPTCHA_SECRET \ -d response=TOKEN \ -d remoteip=VISITOR_IP \ -d sitekey=HCAPTCHA_SITEKEY

becomes

curl https://api.captchafox.com/siteverify \ -d secret=YOUR_SECRET \ -d response=TOKEN \ -d remoteIp=VISITOR_IP \ -d sitekey=YOUR_SITEKEY

The response fields stay the same: success, challenge_ts, hostname and error-codes. See Verify the Response.

Update your Content Security Policy

If your site uses a Content Security Policy, remove the hCaptcha sources (hcaptcha.com, *.hcaptcha.com) and add the CaptchaFox sources.

Switch libraries

If you use an hCaptcha library for your frontend or backend, switch to one of our libraries. See all integrations  for the full list.

Test your migration

  1. Submit the protected form.
  2. Check that your server receives the cf-captcha-response field.
  3. Check that the verification request returns "success": true.

To test without a site, use the test keys. Replace them with your real keys before going live.

Last updated on