Skip to content
Browse the docs

Send server hits and conversions

Your server can tell Spurn about paid landings and orders directly. A server hit gives Spurn the visitor's IP even when the page's JavaScript never runs; a conversion ties an order to the click that brought it. Use this when Spurn has no plugin for your stack.

Before you start#

  • A secret key: Sites, then your site, then the Keys tab. It looks like sp_sec_… and is shown once, when you create it.
  • Keep it on the server. Never put a secret key in a page, an app bundle or a public repository. If one leaks, revoke it and create a new one.
  • The tag on your pages as well (/docs/install/custom). Server hits add a witness; the tag adds browser signals and engagement.

Both endpoints take JSON and the secret key as a bearer token:

Authorization: Bearer sp_sec_XXXXXXXXXXXXXXXXXXXXXXXX
Content-Type: application/json

Server hits: POST /api/v1/hit#

Send one when a page request arrives. Spurn ignores anything that isn't a paid landing and answers 204, so you can send every page request and let Spurn decide, or check for a click id first and save the request.

Field
urlThe full landing URL, query string included.
ipThe visitor's IP. Behind a proxy or CDN, take it from the header your proxy sets, not the socket.
uaThe visitor's user agent.
refOptional. The referrer.
tsOptional. When the landing happened, ISO 8601.
langOptional. The Accept-Language value.
sourcecustom for your own code (node for a Node.js server).
curl -X POST https://spurn.io/api/v1/hit \
  -H "Authorization: Bearer sp_sec_XXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://shop.example.com/?gclid=test-123","ip":"203.0.113.7","ua":"Mozilla/5.0","ref":"https://www.google.com/","lang":"en-GB","source":"custom"}'

A hit for a click the tag already reported (same click id, within 10 minutes) merges into that click. Otherwise Spurn creates a server-only click. Either way it is one click and one credit.

Never make the visitor wait. Send the hit without awaiting it, with a short timeout, and ignore failures. In Node.js:

function sendSpurnHit(req) {
  fetch('https://spurn.io/api/v1/hit', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.SPURN_SECRET_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      url: `https://shop.example.com${req.url}`,
      // Behind Cloudflare, use req.headers['cf-connecting-ip'] instead.
      ip: req.socket.remoteAddress,
      ua: req.headers['user-agent'] ?? '',
      ref: req.headers.referer,
      lang: req.headers['accept-language']?.split(',')[0],
      source: 'node',
    }),
    signal: AbortSignal.timeout(1000),
  }).catch(() => {})
}

Build url from your configured public origin, not from the Host header, which a client can set to anything.

Conversions: POST /api/v1/conversion#

Send one when an order is paid or a lead is confirmed.

Field
orderIdYour order or lead id.
valueThe value in major units (49.9 for $49.90).
currencyISO 4217, such as USD.
clickIdOptional. The click id from the _spc cookie or your own records.
pageviewIdOptional. The page view id from the _spc cookie.
visitorIdOptional. The tag's visitor id (_sp_v in local storage).
tsOptional. When it happened, ISO 8601.

Send at least one of clickId, pageviewId and visitorId. Spurn matches the conversion to the most recent click from the last 30 days with any of them.

The tag writes _spc on a paid landing as {pageviewId}.{clickId}, with - when there is no click id. Read it while the shopper is on your site (at checkout) and store it with the order, because a payment webhook arrives without the shopper's cookies.

curl -X POST https://spurn.io/api/v1/conversion \
  -H "Authorization: Bearer sp_sec_XXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"orderId":"1001","value":49.9,"currency":"USD","pageviewId":"6f1c2e1a-1b7d-4c8e-9a51-2f0d3c4b5a69","clickId":"test-123"}'

Tracking template: GET /c/{siteKey}#

For Google Ads and Microsoft Ads, the tracking template records the IP behind every click with no code on your server. Google and Microsoft call it from the visitor's browser alongside the landing. Set it at account level, with your public key.

Google Ads:

https://spurn.io/c/sp_pub_XXXX?gclid={gclid}&cid={campaignid}&agid={adgroupid}&kw={keyword}&mt={matchtype}&net={network}&pl={placement}&dev={device}&u={lpurl}

Microsoft Ads:

https://spurn.io/c/sp_pub_XXXX?msclkid={msclkid}&cid={CampaignId}&agid={AdGroupId}&kw={keyword:}&mt={MatchType}&net={Network}&dev={Device}&u={lpurl}

More in /docs/guides/tracking-template.

Check it works#

  1. Add your server's and your own IP addresses to the allowlist in Spurn (Blocking, then Allowlist), so your tests are never blocked.
  2. Send the curl hit above with a new click id. A 2xx means it was accepted.
  3. Open Clicks in Spurn. The click appears, and the site's Install tab shows the time of the last server hit.

A test hit counts as a real paid click and uses one credit.

Troubleshooting#

401. The key is missing, revoked, or a public key. These endpoints need the secret key.

204 and nothing in Spurn. The url isn't a paid landing: it needs an ad click id or paid UTM tags.

429. Too many requests. Wait for the seconds in Retry-After.

Every click has the same IP. That is your proxy's address. Read the header your proxy sets, and only trust a header your proxy really sets.

Conversions don't match. Check you send the _spc values from the shopper's paid session, and that the click was within the last 30 days.

What data is sent#

Only what you put in the request: for hits, the landing URL, IP address, user agent, referrer and language; for conversions, the order id, value, currency and the Spurn ids. Full reference: /docs/api.