Challenge migration guide

Migrate from hCaptcha to Botpoison Challenge

Three edits: swap hCaptcha's script for ours, move the key onto the form, and replace the siteverify call with one verify call. Your form keeps its fields, its layout and its thank-you page.

Last verified 16 October 2026

Migrate this project's forms from hCaptcha to Botpoison Challenge.
Follow the guide at https://botpoison.com/migrate/from-hcaptcha.md
Make the three edits it describes, and keep the form's fields and routes.

Why sites move off hCaptcha

hCaptcha asks some visitors to label images. That is the step people give up on, and the one many people with low vision or a screen reader cannot do at all.

Its siteverify call takes form-encoded data only, and a risk score comes with the Enterprise plan. On the other plans the answer is pass or fail.

And a CAPTCHA only asks whether a person is there. Spam a person types still arrives. Botpoison puts Classify for that on the same plan.

What maps to what

Script: hCaptchajs.hcaptcha.com/1/api.js; Challengeunpkg.com/@botpoison/browser

On the form: hCaptchaAn h-captcha div with data-sitekey; Challengedata-botpoison-public-key on the form itself

Field posted: hCaptchah-captcha-response; Challenge_botpoison

Server check: hCaptchaPOST to api.hcaptcha.com/siteverify, form-encoded, with the secret and the response; ChallengeThe same form POSTed to /verify, with secretKey and solution

Result: hCaptchasuccess, and on Enterprise a score; Challengeok, true or false

	hCaptcha	Challenge
Script	`js.hcaptcha.com/1/api.js`	`unpkg.com/@botpoison/browser`
On the form	An `h-captcha` div with `data-sitekey`	`data-botpoison-public-key` on the form itself
Field posted	`h-captcha-response`	`_botpoison`
Server check	POST to `api.hcaptcha.com/siteverify`, form-encoded, with the secret and the response	The same form POSTed to `/verify`, with `secretKey` and `solution`
Result	`success`, and on Enterprise a `score`	`ok`, true or false

The three edits. Off hCaptcha, onto Challenge

Swap the script

Remove hCaptcha's script tag and add ours. It loads async, like theirs did.

HTML

-<script src="https://js.hcaptcha.com/1/api.js" async defer></script>
+<script src="https://unpkg.com/@botpoison/browser" async></script>

Swap the key on the form

Delete the widget's div and put your public key on the form itself. Nothing renders in its place.

HTML

 <form
   action="/contact"
   method="POST"
+  data-botpoison-public-key="pk_xxxxxxxx"
 >
   <textarea name="message"></textarea>
-  <div class="h-captcha" data-sitekey="your_site_key"></div>
   <button type="submit">Send</button>
 </form>

Swap the check on your server

Post the same form to /verify: secretKey and _botpoison in place of secret and h-captcha-response, and ok in place of success.

JavaScript

-const hcaptcha = await fetch("https://api.hcaptcha.com/siteverify", {
+const verified = await fetch("https://api.botpoison.com/verify", {
   method: "POST",
   body: new URLSearchParams({
-    secret: process.env.HCAPTCHA_SECRET,
-    response: req.body["h-captcha-response"],
+    secretKey: process.env.BOTPOISON_CHALLENGE_SECRET_KEY,
+    solution: req.body._botpoison,
   }),
 });
-const { success: ok } = await hcaptcha.json();
+const { ok } = await verified.json();
 if (!ok) return res.status(403).end();

PHP

-$hcaptcha = file_get_contents("https://api.hcaptcha.com/siteverify", false, stream_context_create(["http" => [
+$verified = file_get_contents("https://api.botpoison.com/verify", false, stream_context_create(["http" => [
   "method" => "POST",
   "header" => "Content-Type: application/x-www-form-urlencoded",
   "content" => http_build_query([
-    "secret" => getenv("HCAPTCHA_SECRET"),
-    "response" => $_POST["h-captcha-response"],
+    "secretKey" => getenv("BOTPOISON_CHALLENGE_SECRET_KEY"),
+    "solution" => $_POST["_botpoison"],
   ]),
 ]]));
-$ok = json_decode($hcaptcha)->success;
+$ok = json_decode($verified)->ok;
 if (!$ok) { http_response_code(403); exit; }

Python

-hcaptcha = requests.post("https://api.hcaptcha.com/siteverify", data={
-    "secret": os.environ["HCAPTCHA_SECRET"],
-    "response": request.form["h-captcha-response"],
+verified = requests.post("https://api.botpoison.com/verify", data={
+    "secretKey": os.environ["BOTPOISON_CHALLENGE_SECRET_KEY"],
+    "solution": request.form["_botpoison"],
 })
-ok = hcaptcha.json()["success"]
+ok = verified.json()["ok"]
 if not ok:
     abort(403)

-res, err := http.PostForm("https://api.hcaptcha.com/siteverify", url.Values{
-  "secret":   {os.Getenv("HCAPTCHA_SECRET")},
-  "response": {r.FormValue("h-captcha-response")},
+res, err := http.PostForm("https://api.botpoison.com/verify", url.Values{
+  "secretKey": {os.Getenv("BOTPOISON_CHALLENGE_SECRET_KEY")},
+  "solution":  {r.FormValue("_botpoison")},
 })
 if err != nil {
   http.Error(w, "", http.StatusBadGateway)
   return
 }
-var out struct{ Ok bool `json:"success"` }
+var out struct{ Ok bool `json:"ok"` }
 json.NewDecoder(res.Body).Decode(&out)
 if !out.Ok {
   http.Error(w, "", http.StatusForbidden)
   return
 }

Shell

-curl "https://api.hcaptcha.com/siteverify" \
-  --data-urlencode "secret=$HCAPTCHA_SECRET" \
-  --data-urlencode "response=<the h-captcha-response field>"
-# {"success": true, ...}
+curl "https://api.botpoison.com/verify" \
+  --data-urlencode "secretKey=$BOTPOISON_CHALLENGE_SECRET_KEY" \
+  --data-urlencode "solution=<the _botpoison field>"
+# {"ok": true, ...}

What behaves differently

No widget. Nothing renders on the page, and nobody is shown an image.

No reCAPTCHA compatibility hook. hCaptcha can stand in for grecaptcha. Challenge does not, so remove any hcaptcha or grecaptcha calls with the script, and read _botpoison on the server.

The check runs on Send. Nothing runs while the page loads, so a visitor who never submits costs nothing.

Questions

Does Challenge fill in the field hCaptcha used?: No. Challenge posts one field, _botpoison, and your server reads that one.
Is there a test key, like hCaptcha's?: Yes. With the secret key test, the solution ok passes and any other fails. See test mode.
Moving from reCAPTCHA or Turnstile instead?: See the guides from reCAPTCHA and from Turnstile.

Sources

hCaptcha developer guide hCaptcha documentation
Switch from reCAPTCHA to hCaptcha hCaptcha documentation

hCaptcha is a trademark of hCaptcha. Botpoison is not affiliated with hCaptcha.

Other migration guides

To Challenge

Invisible CAPTCHA alternative

From reCAPTCHA
v2 checkbox, v2 invisible or v3 score. Swap the script, the key and the siteverify call.
From Turnstile
Drop the cf-turnstile widget. The check runs fresh on each Send and moves to one verify call.

To Classify

Spam classifier

From Akismet
comment-check answers "true" or "false" as text. Classify answers a label, and a score to hold the borderline ones on.
From OOPSpam
A score from 0 to 6 against your threshold becomes a label, with the score kept for a review queue.

Switch to Challenge for free

Stop spam now

No credit card required

Three edits

Your fields stay as they are

Free to start