wsCAPTCHA integration
wsCAPTCHA is a click-to-verify widget that keeps bots out of the forms on your website. It is free, it works on any site and it does not need a Web Protection subscription.
How it checks a visitor
The visitor ticks a box. The browser solves a small signed puzzle and sends it with a few technical browser details. WireShield scores the answer together with threat intelligence:
- Low score: the visitor passes at once.
- Medium score: the visitor is asked to press and hold, which takes about a second.
- High score: the answer is rejected.
The recent behaviour of the address also counts. Repeated failures, or very many passes for the same key and site, make the next attempt harder. A puzzle is signed for the site and the browser, is valid for five minutes and works once.
1. Create a key
Sign in to your WS Account, open wsCAPTCHA and choose Create key. Give the key a name and list the domains it may be used on (sub-domains are included). You get a site key (wsk_…) for the page and a secret (wss_…) for your server.
The secret is shown once, when you create or renew the key. WireShield stores only a hash of it. Copy it to your server settings straight away.
2. Place the widget
<script src="https://captcha.wireshield.network/v1/api.js" async defer></script>
<form action="/register" method="post">
<input type="email" name="email" required>
<div class="ws-captcha" data-sitekey="YOUR_SITE_KEY"></div>
<button type="submit">Send</button>
</form>
When the visitor has passed, the form sends a token in the field ws-captcha-response.
| Attribute | Meaning |
|---|---|
data-sitekey | Your site key (required). |
data-theme | light or dark. |
data-lang | Widget language, tr or en. Default: the language of the page. |
data-callback | Name of a function called with the token after a pass. |
data-expired-callback | Called when the token has expired. |
data-error-callback | Called with an error code: quota-exceeded, invalid-domain, invalid-sitekey or network-error. |
data-response-field-name | Name of the form field that carries the token. Default: ws-captcha-response. |
To draw the widget yourself, load api.js?render=explicit and call wscaptcha.render(element, options). api.js?onload=myFunction calls your function when the script is ready. wscaptcha.reset() clears the widget and wscaptcha.getResponse() returns the current token.
3. Verify on your server
Never trust the form alone. Post the token and your secret to the verification URL and accept the form only when success is true.
curl -X POST https://captcha.wireshield.network/v1/siteverify \
-d "secret=YOUR_SECRET" \
-d "response=TOKEN"
# {"success":true,"hostname":"example.com","challenge_ts":"2026-10-26T00:42:02Z","error-codes":[]}
| Error code | Meaning |
|---|---|
missing-input-secret, invalid-input-secret | The secret is missing or not recognised. |
missing-input-response, invalid-input-response | The token is missing, invalid or expired. |
timeout-or-duplicate | The token was already used. |
A token works once. Decide in your code what to do when the verification request itself fails (for example a timeout): accept the form or reject it.
Switching from reCAPTCHA, hCaptcha or Turnstile
You change four values and leave the rest of your form and server code as it is.
| reCAPTCHA | hCaptcha | Turnstile | wsCAPTCHA | |
|---|---|---|---|---|
| Script | www.google.com/recaptcha/api.js | js.hcaptcha.com/1/api.js | challenges.cloudflare.com/turnstile/v0/api.js | captcha.wireshield.network/v1/api.js |
| Element class | g-recaptcha | h-captcha | cf-turnstile | ws-captcha |
| Form field | g-recaptcha-response | h-captcha-response | cf-turnstile-response | ws-captcha-response |
| Verification URL | …/recaptcha/api/siteverify | api.hcaptcha.com/siteverify | …/turnstile/v0/siteverify | captcha.wireshield.network/v1/siteverify |
The verification answer has the same shape: success, hostname, challenge_ts and error-codes. To keep your server code untouched, set data-response-field-name to the field name you already read, for example data-response-field-name="g-recaptcha-response".
wsCAPTCHA is a visible click-to-verify widget. Invisible, score-based checks such as reCAPTCHA v3 have no equivalent.
Remember to add the WireShield addresses to your Content-Security-Policy if you use one: https://captcha.wireshield.network for scripts and connections.
Limits
- Monthly verifications: the successful verifications of your account in a month are counted and shown in your portal. When the limit is reached, the widget answers
quota-exceededuntil the end of the month. Tokens already issued still pass verification. You receive an email at 80% and at 100%. - Keys: the number of keys per account is limited as well.
- Rate limits: per address, 120 puzzles and 60 answers per minute. The verification URL accepts 1200 requests per minute.
Need higher limits? Contact us from the contact page.
Using wsCAPTCHA with Web Protection
If your site is protected with WireShield Web Protection, you can use wsCAPTCHA as the interactive challenge in the challenge settings. No key is needed for that. The answer is checked on your own domain, and a successful pass sets a clearance cookie.