AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

turnstile-spin

Set up, repair, or migrate to Cloudflare Turnstile bot verification in an existing frontend and backend, including server-side Siteverify.

Original source
cloudflare
License
Apache-2.0
Pinned revision
e44f580f9c4fa3bf268e284ae7706c7954ba31fd

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read cloudflare--turnstile-spin at revision e44f580f9c4fa3bf268e284ae7706c7954ba31fd, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 10

references/hugo.md

Hugo

For Hugo static sites. The widget renders on any page that includes the partial; siteverify happens at whatever backend handles your form submissions (a Cloudflare Pages Function, a Worker, an external API, or a form host with a server-side hook).

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

<form action="{{ .Site.Params.turnstileFormEndpoint }}" method="POST">
	<input name="email" type="email" required />
	<div
		class="cf-turnstile"
		data-sitekey="{{ .Site.Params.turnstileSitekey }}"
		data-action="subscribe"
	></div>
	<button type="submit">Subscribe</button>
</form>

Add the params to your site config:

[params]
turnstileSitekey = "YOUR_SITEKEY"
turnstileFormEndpoint = "/api/subscribe"  # path to your existing form handler

Reference the partial from any layout or content file:

{{ partial "turnstile.html" . }}

Backend (where siteverify lives)

Hugo doesn't host server-side code, so the form endpoint must live elsewhere. Two common setups:

Cloudflare Pages Function (functions/api/subscribe.js):

export async function onRequestPost({ request, env }) {
	const form = await request.formData();
	const token = form.get("cf-turnstile-response");

	const expectedHostnames = new Set(
		(env.TURNSTILE_HOSTNAMES ?? "")
			.split(",")
			.map((h) => h.trim())
			.filter(Boolean),
	);
	if (expectedHostnames.size === 0) {
		return new Response("forbidden", { status: 403 });
	}

	const r = await fetch("https://challenges.cloudflare.com/turnstile/v0/siteverify", {
		method: "POST",
		headers: { "Content-Type": "application/x-www-form-urlencoded" },
		body: new URLSearchParams({
			secret: env.TURNSTILE_SECRET,
			response: token,
			remoteip: request.headers.get("CF-Connecting-IP"),
		}),
	});
	const result = await r.json();
	if (
		r.ok !== true ||
		result.success !== true ||
		result.action !== "subscribe" ||
		!expectedHostnames.has(result.hostname)
	) {
		return new Response("forbidden", { status: 403 });
	}

	// process subscribe
	return new Response("ok");
}

subscribe is the stable action for this surface. Preserve an existing custom migration action and compare the returned action to the same value. Siteverify is mandatory for every widget mode, including pre-clearance. Set TURNSTILE_HOSTNAMES to the deployment-specific frontend hostnames; a production value must not include localhost or 127.0.0.1.

After the user approves a canonical absolute WRANGLER_BIN outside the project, set the secret with (set +x; printf '%s' "$WIDGET_SECRET" | "$WRANGLER_BIN" pages secret put TURNSTILE_SECRET) (or use the dashboard's Pages → your project → Settings → Environment variables → Add secret).

External backend: any Node/Ruby/Python/Go handler can do the same call. See the vanilla-html reference for non-Cloudflare-specific snippets.

Variant: shortcode for content files

If you want to drop the widget into Markdown content (not just layouts), create a shortcode:

{{ partial "turnstile.html" . }}

Use in content:

---
title: Contact
---

Contact us:

{{< turnstile-form >}}

Substitutions

| Placeholder | Replace with | | ------------------------ | -------------------------------------------------------------------- | | YOUR_SITEKEY | The widget site key from Step 8 | | turnstileFormEndpoint | The path or URL to your form handler (Pages Function, Worker, etc.) | | TURNSTILE_SECRET | Env-var name in your backend. Value is the secret captured in Step 8.|