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 tokenUpdate 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_SITEKEYbecomes
curl https://api.captchafox.com/siteverify \
-d secret=YOUR_SECRET \
-d response=TOKEN \
-d remoteIp=VISITOR_IP \
-d sitekey=YOUR_SITEKEYThe 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
- Submit the protected form.
- Check that your server receives the
cf-captcha-responsefield. - 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.