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
| Result | HTTP | Error code |
|---|---|---|
| Valid token | 201 / 200 | — |
| Missing or invalid token | 403 | verification_failed |
| Wrong hostname or action | 403 | verification_failed |
| Provider outage | 503 | temporarily_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.