070082 vanrossum.dev
home/veldform/docs

Veldform / Docs

Anti-spam

Every form is protected out of the box — no configuration needed. On top of that, you can enable a captcha for the whole site.

One thing to know up front: spam is never stored. There is no spam folder to review — a submission that trips the protection simply never becomes an entry, and no actions run for it.

Always-on protection

Two guards are active on every form, and can't be turned off:

  • Honeypot — an invisible field that humans never see. Bots that fill it in get a fake success response, so they don't learn anything.
  • Time-trap — a form that is submitted within two seconds of being rendered is treated as a bot, and also gets a fake success response.

There's also rate limiting: more than 30 submissions per minute from the same device are rejected with a "Too many submissions" error. If that limit doesn't fit your use case, it's adjustable with the veldform/submit/rate_limit filter — see Action and filter hooks.

Captcha

For an extra layer, Veldform supports two captcha providers:

  • Cloudflare Turnstile (recommended) — shows a small, unobtrusive widget
  • Google reCAPTCHA v3 — fully invisible, score-based

To set it up:

  • Go to Veldform -> Settings and look for Spam protection
  • Pick your captcha provider
  • Fill in the Site key and Secret key you got from the provider, and save

The secret key is stored encrypted, and is never sent back to the browser.

Once the keys are saved, the captcha is active on every form. Individual forms can opt out: on the form's Settings tab, under Spam protection, disable Verify submissions with the site-wide captcha.

Unlike the honeypot and time-trap, a failed captcha check is not silent — the visitor sees "The spam check could not verify your submission. Please try again." and their input is preserved, so a real person who gets flagged can simply retry.

For reCAPTCHA v3, the minimum score defaults to 0.5. You can tune it with the veldform/captcha/recaptcha_min_score filter.

Adding your own provider

Captcha providers are a registry, just like fields and actions. Third-party providers can be added with the veldform/register_captcha filter — see Action and filter hooks.