Protect your form with CAPTCHA

A form on a public website gets sign-ups from bots sooner or later. Every form already has a hidden trap field that most bots fill in, and a limit on how often one IP address can send. For forms that still get spam, switch on a CAPTCHA: a Cloudflare Turnstile check that the visitor passes before the form is sent. Most people pass it without doing anything; a few are asked to tick a box.

Turnstile is free. You need a Cloudflare account, but your website does not have to use Cloudflare.

1. Create a Turnstile widget in Cloudflare

  1. Sign in at dash.cloudflare.com (or create a free account).
  2. Open Turnstile in the menu and choose Add widget.
  3. Give it a name you will recognise, such as "Website forms".
  4. Under Hostnames, add every domain where your forms show:
    • your website, for example example.com and www.example.com;
    • crm.codefab.dev, if you share the form's own page (the /public/f/… link) or want to use Test in the CRM.
  5. Keep Widget mode on Managed. It shows the box only to visitors Cloudflare is unsure about.
  6. Save. Cloudflare shows two keys: a site key and a secret key.

2. Add the keys in the CRM

  1. Open Settings → Bot protection (admins only). The same card is at the top of Forms & surveys.
  2. Paste the site key and the secret key, then choose Save.
  3. The CRM checks the secret key with Cloudflare before saving it. A key Cloudflare doesn't accept is refused with a message, so a copy-paste mistake shows up here and not as lost sign-ups.
  4. Choose Test the site key to see Cloudflare's check right there. If it says Cloudflare refused it, add crm.codefab.dev to the widget's hostnames, or test on your website instead.

One pair of keys serves all of your organisation's forms. The secret key is stored encrypted and is never shown again; to change it, save a new pair. Remove deletes the keys, and forms stop showing the check.

3. Switch it on per form

Open the form, switch on Protect with CAPTCHA and save. The check appears above the send button, both on the form's own page and where the form is embedded on your website. It follows the form's theme: data-theme="dark" on the embed script gives a dark check too (see Style your form).

A form with CAPTCHA switched on refuses any answer that hasn't passed the check. The setting is also in the API as captchaEnabled on /api/v1/signup-forms, and the keys are set with PUT /api/v1/settings/turnstile.

If sign-ups stop

  • The check shows an error on your site: the site's domain is missing from the widget's hostnames in Cloudflare. Add it there; nothing changes in the CRM.
  • Every answer is refused: the keys in the CRM belong to a different widget, or the widget was deleted in Cloudflare. Copy both keys from the widget again and save them.
  • The check doesn't show at all: your site's Content Security Policy blocks Cloudflare. Allow https://challenges.cloudflare.com in script-src and frame-src.