Server-Side Events (S2S)

The browser pixel (s.js) is the easy way to record on-page events, but it’s structurally blockable: Brave, ad blockers, and privacy modes drop it, and it can’t run at all inside a native mobile app. Server-side events are the durable alternative — your own backend sends the event straight to Synaptyx over HTTPS, authenticated with an API key.

It’s the server-to-server counterpart of the pixel, and it lands in the same pixel-event store — so these events show up in your funnels, journeys, and source analytics next to the browser ones.

When to use it

• Mobile apps — no browser, no pixel. Send signup, login, checkout from your app’s backend.
• Ad-blocked web traffic — mirror your key pixel events server-side so they survive Brave / uBlock.
• Backend-only milestones — events that only your server knows about (trial converted, subscription renewed, KYC passed…).

Authentication & scope

Send the event with an API key carrying the write:events scope (the only write scope on the v1 API — available on Pro and Scale).

curl -X POST https://app.synaptyx.pro/api/v1/events \
  -H "Authorization: ApiKey syx_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "click_id": "V1StGXR8_Z5jdHi6B-myT", "event_name": "checkout", "value": 49.9, "currency": "EUR" }'

Create a key in Settings → API Keys and tick write:events (under Advanced).

The endpoint

Request body

Which attribution key to send

An event has to attach to something. Send whichever key you have:

With a click_id, Synaptyx resolves the click → its campaign, and the campaign must belong to your account. campaignId / userId are derived from the resolved click, never from your payload, so you can’t inject events onto someone else’s traffic — and a campaign_id in the body is ignored. With a visitor_id, you name the campaign and we check you own it before accepting anything.

Carrying the attribution key

The whole game is getting the key from the acquisition moment to the place that fires the event. Four patterns:

landing ?clickid=… ──▶ store on user/order ──▶ POST /api/v1/events { click_id, … }

pixel sets _syx_vid ──▶ your backend reads the cookie ──▶ POST /api/v1/events
                                                          { visitor_id, campaign_id, … }

// Express / Node — the cookie is already on the request
const visitorId = req.cookies._syx_vid;

/t/… redirect ──▶ store / deep link ──▶ app stores click_id ──▶ backend events

Validation, limits & abuse controls

• Strict shapes — the IDs and event_name are regex-validated; a bad value returns 400 (it is never stored loosely).
• properties sanitisation — over-limit keys, non-primitive values, and oversized blobs are dropped, but the event still goes through with the valid fields.
• Idempotency — pass event_id to make retries safe; a duplicate within 24h is a no-op.
• Rate limits — per API key (standard X-RateLimit-* headers, see Limits) and a per-identifier cap, so one click or visitor can’t be spammed with events.

Responses

Examples

curl -X POST https://app.synaptyx.pro/api/v1/events \
  -H "Authorization: ApiKey syx_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "click_id": "V1StGXR8_Z5jdHi6B-myT",
    "event_name": "checkout",
    "value": 49.9,
    "currency": "EUR",
    "event_id": "order_8421",
    "properties": { "plan": "pro", "seats": 3 }
  }'

curl -X POST https://app.synaptyx.pro/api/v1/events \
  -H "Authorization: ApiKey syx_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "visitor_id": "k3n8v1qwz9r2mx7cms4ussbe",
    "campaign_id": "cmnvqgg5n03vo01n0as05a0n1",
    "event_name": "signup"
  }'

await fetch("https://app.synaptyx.pro/api/v1/events", {
  method: "POST",
  headers: {
    Authorization: "ApiKey syx_live_your_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    click_id: order.synaptyxClickId,   // stored at signup
    event_name: "checkout",
    value: order.total,
    currency: order.currency,
    event_id: order.id,                // safe to retry
    properties: { plan: order.plan },
  }),
});

import requests
 
requests.post(
    "https://app.synaptyx.pro/api/v1/events",
    headers={"Authorization": "ApiKey syx_live_your_key_here"},
    json={
        "click_id": order.synaptyx_click_id,  # stored at signup
        "event_name": "checkout",
        "value": order.total,
        "currency": order.currency,
        "event_id": order.id,                 # safe to retry
        "properties": {"plan": order.plan},
    },
    timeout=5,
)

Server-side events vs. conversions

Next