Install the Spurn Cloudflare Worker
For any site behind Cloudflare, the Spurn Worker sends a server hit from the edge when a paid click lands. It passes every request through to your site untouched and never waits for Spurn.
What it adds#
The tag in the browser sees the visitor's device and behaviour. The Worker sees every paid landing that reaches Cloudflare, including bots that never run JavaScript, with the real IP from CF-Connecting-IP. Use both: the Worker is a second witness, not a replacement for the tag. Install the tag first with the guide for your platform, or /docs/install/custom.
Before you start#
- The site's DNS on Cloudflare with the proxy on (orange cloud).
- Node.js and Wrangler, Cloudflare's CLI (
npx wranglerworks without a global install). - Your site's secret key from Spurn: Sites, then your site, then the Keys tab. It looks like
sp_sec_…and is shown once, when you create it. - The Worker's code: the
integrations/cloudflare-workerfolder Spurn provides.
1. Configure#
Create wrangler.toml in the Worker folder, with your own hostname and zone:
name = "spurn-edge"
main = "src/index.ts"
compatibility_date = "2026-11-01"
routes = [
{ pattern = "shop.example.com/*", zone_name = "example.com" }
]
[vars]
SPURN_ENDPOINT = "https://spurn.io"
Add a route for each hostname your ads land on, for example both example.com/* and www.example.com/*.
2. Add the secret key#
npx wrangler secret put SPURN_SECRET_KEY
Paste the secret key when asked. It is stored encrypted by Cloudflare and never appears in wrangler.toml or your repository.
3. Deploy#
npx wrangler deploy
How it behaves#
- Every request goes to your origin exactly as it came in, and the response comes back unchanged.
- Only a page request whose URL has an ad click id or paid UTM tags sends a hit. Assets, API calls and organic visits send nothing.
- The hit (URL, IP from
CF-Connecting-IP, user agent, referrer and language) is sent withctx.waitUntil, after the response has left. A slow or failed call to Spurn never delays or breaks your site. - If anything in the Worker itself fails, the request still goes to your origin.
The Worker runs on every request matching its routes, assets included, and each one counts toward your Cloudflare Workers usage. Check your plan's request allowance against your traffic.
Check it works#
- Add your own IP address to the allowlist in Spurn (Blocking, then Allowlist), so your tests are never blocked.
- Open
https://shop.example.com/?gclid=test-123. - In Spurn, the site's Install tab shows Receiving and the time of the last server hit. The click appears under Clicks.
A test landing counts as a real paid click and uses one credit. To watch the Worker live, run npx wrangler tail.
Troubleshooting#
No server hits. Check the route pattern matches the hostname in your test URL, the DNS record is proxied, and SPURN_SECRET_KEY is set (npx wrangler secret list).
Clicks are rejected for the wrong site. Spurn checks the landing host against your site's domain and extra hosts. Add every hostname in your routes to the site in Spurn.
Another Worker already runs on the route. Only one Worker handles a request. If another Worker already serves the hostname, send the hit from that Worker instead, using /docs/install/server-api.
Every click shows a Cloudflare address. The Worker reads CF-Connecting-IP, which Cloudflare sets to the visitor's address. If you see Cloudflare's own ranges, another proxy in front of Cloudflare is forwarding the traffic.
What data is sent#
On paid landings only: the landing URL, the visitor's IP address and user agent, the referrer and the Accept-Language value. Nothing is sent for organic visits, and nothing about your responses.