Turnstile integration

Render the widget, send the token and handle verification failures correctly.

Turnstile is verified server-side by Postvia. The expected hostname is the customer website origin, not api.postvia.dev. A provider outage fails closed with a retryable 503.

Widget

<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>

<div
  class="cf-turnstile"
  data-sitekey="YOUR_PUBLIC_SITE_KEY"
  data-action="contact"
  data-callback="onTurnstileSuccess"
  data-expired-callback="onTurnstileExpired"
></div>

Send the token in the reserved field:

{
  "name": "John Smith",
  "email": "[email protected]",
  "message": "Hello",
  "cf-turnstile-response": "TURNSTILE_TOKEN"
}

Rules

  • The token is single use.
  • Do not retry an invalid or expired token automatically.
  • Reset the widget after success and after a used token.
  • Never put the Turnstile secret in frontend code.
  • Keep the widget action aligned with the action configured in Postvia.
  • Allow the Cloudflare challenge domain in your CSP if you have a strict policy.

Behaviour

ResultHTTPError code
Valid token201 / 200—
Missing or invalid token403verification_failed
Wrong hostname or action403verification_failed
Provider outage503temporarily_unavailable

Replays

An identical idempotent replay returns 200 before Turnstile verification, because it creates nothing. A new submission or changed payload needs a fresh token.

See Security and spam protection.