Captcha
Protect a FormDB form with the built-in captcha, which needs no keys, or with reCAPTCHA v2, reCAPTCHA v3, hCaptcha or Cloudflare Turnstile using your own keys.
This page shows how to protect a form with a captcha. FormDB has a built-in captcha that needs no keys, and also supports reCAPTCHA v2, reCAPTCHA v3, hCaptcha and Cloudflare Turnstile with your own keys from the provider. FormDB verifies each submission for you.
A captcha is a check that tries to tell people from bots, such as a tick box or an invisible score. It is available on every plan.
Built-in captcha (no keys)
The FormDB (built in, no keys) provider is a proof-of-work check, powered by ALTCHA, that runs in the visitor's browser. There is no account to create and there are no keys to paste.
- Open the form and go to the Settings tab.
- In the Captcha card, set Provider to FormDB (built in, no keys) and click Save.
- Copy the updated snippet from the Setup tab. It adds the widget script and this element inside your form:
<altcha-widget challenge="https://api.formdb.io/f/your-form-id/challenge" name="altcha"></altcha-widget>The widget fetches a challenge for the form, solves it and adds the result as a hidden field named altcha. Each challenge expires after 10 minutes and can be used once.
How it works with your own keys
- You create a captcha in your provider's dashboard. The provider gives you two keys: a site key, which is public and goes in your web page, and a secret key, which is private.
- You save both keys in FormDB.
- The captcha widget on your page produces a token and adds it to the form as a hidden field.
- FormDB receives the token with the submission and asks the provider whether it is valid. If not, the submission is rejected.
Each form uses one provider at a time.
Set it up in FormDB
- Open the form and go to the Settings tab.
- In the Captcha card, choose a Provider.
- Paste your Site key and Secret key. The link Where do I find this? opens the provider's documentation.
- For reCAPTCHA v3, set a Minimum score if you want something other than the default of 0.5.
- Click Save.
The secret key is stored encrypted and is never shown again. To keep the saved key when changing other settings, leave the field empty. To turn captcha off, set Provider to None and save. This also removes the stored secret.
Note: Once a captcha is saved, every submission must carry a valid token. Add the widget to your live form right after saving, or real visitors will be rejected.
Token field names
Each provider's widget adds the token under a specific field name. FormDB reads that field and removes it before storing the submission.
Provider | Token field |
|---|---|
reCAPTCHA v2 |
|
reCAPTCHA v3 |
|
hCaptcha |
|
Cloudflare Turnstile |
|
reCAPTCHA v2
reCAPTCHA v2 shows the "I'm not a robot" tick box. Load Google's script and place the widget inside your form. Replace YOUR_SITE_KEY with your site key.
<script src="https://www.google.com/recaptcha/api.js" async defer></script>
<form action="https://api.formdb.io/f/your-form-id" method="POST">
<label for="email">Email</label>
<input type="email" id="email" name="email" required />
<label for="message">Message</label>
<textarea id="message" name="message" required></textarea>
<div class="g-recaptcha" data-sitekey="YOUR_SITE_KEY"></div>
<input type="text" name="_gotcha" tabindex="-1" autocomplete="off" style="display:none" />
<button type="submit">Send</button>
</form>hCaptcha
<script src="https://js.hcaptcha.com/1/api.js" async defer></script>
<form action="https://api.formdb.io/f/your-form-id" method="POST">
<label for="email">Email</label>
<input type="email" id="email" name="email" required />
<label for="message">Message</label>
<textarea id="message" name="message" required></textarea>
<div class="h-captcha" data-sitekey="YOUR_SITE_KEY"></div>
<input type="text" name="_gotcha" tabindex="-1" autocomplete="off" style="display:none" />
<button type="submit">Send</button>
</form>Cloudflare Turnstile
<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>
<form action="https://api.formdb.io/f/your-form-id" method="POST">
<label for="email">Email</label>
<input type="email" id="email" name="email" required />
<label for="message">Message</label>
<textarea id="message" name="message" required></textarea>
<div class="cf-turnstile" data-sitekey="YOUR_SITE_KEY"></div>
<input type="text" name="_gotcha" tabindex="-1" autocomplete="off" style="display:none" />
<button type="submit">Send</button>
</form>reCAPTCHA v3
reCAPTCHA v3 is invisible. Instead of a challenge, Google gives each visitor a score from 0 (likely a bot) to 1 (likely a person). FormDB rejects submissions that score below your Minimum score.
There is no widget, so your page must request a token when the form is submitted and add it as a hidden field:
<script src="https://www.google.com/recaptcha/api.js?render=YOUR_SITE_KEY" async defer></script>
<form id="formdb-form" action="https://api.formdb.io/f/your-form-id" method="POST">
<label for="email">Email</label>
<input type="email" id="email" name="email" required />
<label for="message">Message</label>
<textarea id="message" name="message" required></textarea>
<input type="text" name="_gotcha" tabindex="-1" autocomplete="off" style="display:none" />
<button type="submit">Send</button>
</form>
<script>
const form = document.getElementById("formdb-form");
form.addEventListener("submit", function (event) {
event.preventDefault();
grecaptcha.ready(function () {
grecaptcha.execute("YOUR_SITE_KEY", { action: "submit" }).then(function (token) {
let input = form.querySelector('input[name="g-recaptcha-response"]');
if (!input) {
input = document.createElement("input");
input.type = "hidden";
input.name = "g-recaptcha-response";
form.appendChild(input);
}
input.value = token;
form.submit();
});
});
});
</script>Generated snippets
After you save a provider and site key, the code on the form's Setup tab and in the builder's Code tab includes the captcha for you. A few things to know:
- The HTML snippet is complete for all four providers.
- The React snippet includes the widget, and shows the script tag as a comment for you to add to your
index.html. - The Vue snippet includes the widget but not the script tag. Add the script tag to your page yourself.
- For reCAPTCHA v3, only the HTML snippet contains the code that requests a token. In React or Vue, call
grecaptcha.executeyourself and add the token to the data you send. - The Fetch and jQuery snippets contain no captcha code.
Captcha with JavaScript submissions
For reCAPTCHA v2, hCaptcha and Turnstile, the widget places its token field inside your form. If you submit with new FormData(form), the token is included automatically.
For reCAPTCHA v3, or when you build the request body by hand, add the token under the provider's field name:
grecaptcha.ready(async () => {
const token = await grecaptcha.execute("YOUR_SITE_KEY", { action: "submit" });
const data = new FormData(document.getElementById("formdb-form"));
data.set("g-recaptcha-response", token);
const response = await fetch("https://api.formdb.io/f/your-form-id", {
method: "POST",
headers: { Accept: "application/json" },
body: data,
});
const body = await response.json();
if (!body.ok) {
console.log(body.error.code, body.error.message);
}
});When verification fails
FormDB rejects the submission with status 400 and the code captcha_failed. The message says what went wrong, for example:
hCaptcha token is missing: the token field was not in the submission. Check that the widget is inside the form.hCaptcha verification failed: the provider did not accept the token. Check that the site key and secret key belong to the same captcha and that your domain is allowed in the provider's dashboard.reCAPTCHA v3 score too low: the visitor scored below your minimum score.hCaptcha verification could not be completed: FormDB could not reach the provider. The visitor can try again.
Rejected submissions are not stored and do not use quota.
Testing
The test form on the Setup tab shows the built-in captcha. It does not show a reCAPTCHA, hCaptcha or Turnstile widget, so while one of those is enabled, test submissions from the dashboard are rejected. Test from your own page instead.
Order of checks
The honeypot runs before the captcha. A bot that fills in _gotcha is dropped without the captcha being checked. Validation and the spam filter run after the captcha. See How it works.
Next steps
- Spam protection: the other layers.
- Form settings: all captcha settings and defaults.
- JavaScript and AJAX: handling the
captcha_failederror.
Ready to try it? Create a free account and send your first submission.