How to add a CAPTCHA to a website form, step by step
Updated:
Quick answer
To add a CAPTCHA to a form you (1) get a site key and a secret, (2) load the provider’s widget script on the page, (3) place the widget inside the form so it adds a token field, (4) send the token to your server with the form and (5) verify it with the provider’s API before you process anything. Skipping step 5 is the most common mistake: a check that only runs in the browser can be bypassed by posting to your endpoint directly.
How does a CAPTCHA connect to a form?
Every modern CAPTCHA works in two halves. The client half is a widget (a script and a small element) that runs in the visitor’s browser and produces a one-time token. The server half is an API call from your backend that asks the provider whether that token is valid.
The form itself only has to carry the token. Your server decides what happens next: process the request, reject it, or ask for another check.
Step-by-step: add a CAPTCHA to any form
- Create a project with the provider and note two values: the public site key (goes into your HTML) and the secret key (stays on your server, never in front-end code).
- Load the widget script once on every page that contains a protected form.
- Place the widget element inside the form tag, with the site key. On submit it adds a hidden field with the token.
- Make sure your form handler receives that field, whether the form posts normally or through fetch or XHR.
- On the server, send the secret and the token to the provider’s verification endpoint. Continue only if the answer says the token is valid.
- Reject the request with a clear message if verification fails, and log the failure so you can see attacks in your monitoring.
The mistakes that break CAPTCHA protection
| Mistake | What happens | Fix |
|---|---|---|
| Verifying only in the browser | A bot posts directly to your endpoint and never sees the widget. | Always verify the token on your server. |
| Secret key in front-end code | Anyone can read it and forge “valid” answers. | Keep the secret in server environment variables. |
| Reusing a token | A captured token is replayed many times. | Tokens are single-use: reject a second submission with the same token. |
| No timeout or retry handling | Real users on slow networks are blocked with no message. | Show a clear error and let them retry without losing their input. |
| Widget on pages that do not need it | Extra script weight and friction everywhere. | Load it only on forms that attract abuse. |
How do I test that it works?
- Submit the form normally and confirm that the request goes through.
- Send a request to the same endpoint with no token, with an empty token and with a made-up token. All three must be rejected.
- Submit the same valid token twice. The second request must fail.
- Test with the keyboard only and with a screen reader, so that people using assistive technology are not locked out.
- Watch the form completion rate for a week after launch, to be sure real visitors are not blocked.
Adding BurgCaptcha
BurgCaptcha follows the same two-part pattern. Its API answers in the reCAPTCHA response format, so if your form already verifies reCAPTCHA tokens, switching means changing a script URL, a site key and a secret, not rewriting your handler.
The widget runs a proof-of-work task in the background, shows no puzzle and sets no cookies. The free plan covers 1,000 requests a month, commercial sites included.
Frequently asked questions
Where do I put the CAPTCHA code in my form?
Load the widget script on the page and place the widget element inside the form tag. It adds a hidden token field that is submitted with the other fields.
Do I need server-side verification?
Yes. Without it, a bot can post directly to your form endpoint and skip the widget completely. The server must check the token with the provider before processing the request.
Is it safe to put the site key in my HTML?
Yes. The site key is public by design. Only the secret key must stay on the server.
Can I add a CAPTCHA to a static website?
Yes, if the form posts to a backend or serverless function that can verify the token. A purely static page with no server code cannot verify tokens safely.
How long does the integration take?
For a typical form, an experienced developer needs well under an hour for the widget and the verification call. Testing and error messages take the rest.