How do I send events from my server?

Short answer

Create an API key with the Server track scope, then send events from your backend with one of the server SDKs (Node.js, PHP, Python, Java, Go) or a plain POST /api/v1/track. Give every order or payment an insert_id so retries are not counted twice.

When to send from the server

Send anything that must be counted exactly: purchases, payments, refunds, subscription changes, sign-ups confirmed by your database. The browser script can miss these when a blocker is installed, the tab closes, or the payment completes on another domain. Keep pageviews on the website script so they are not counted twice. Background: server-side tracking.

1. Create a key

Owners and admins open Configuration › Settings › API keys, create a key and include Server track. The key starts with wck_ and is shown only once. Put it in an environment variable or secret manager, never in a repository, a browser or an app.

2. Send an event

With the Node.js SDK:

npm install @tapcub/node

import { TapCub } from '@tapcub/node';

const tc = new TapCub({ apiKey: process.env.TAPCUB_API_KEY });

tc.track('purchase', {
  loginId: user.id,
  insertId: order.id,
  properties: { revenue: 19.9, currency: 'USD' },
});

The SDKs queue events and send them every 3 seconds or every 200 events, and retry network errors, 5xx and 429 up to 5 times. In serverless functions, await tc.flush() before returning.

Without an SDK, post JSON with the key in the Authorization header:

curl -X POST "https://api.pathclue.com/api/v1/track" \
  -H "Authorization: Bearer wck_…" \
  -H "Content-Type: application/json" \
  -d '{"events":[{"event":"purchase","login_id":"u_123","insert_id":"order-1001","properties":{"revenue":19.9}}]}'

One request carries 1 to 1,000 events. time is in milliseconds; a time more than 72 hours from the server clock is replaced with the current time and returned with a warning.

3. Avoid double counting

Set insert_id (at most 36 characters) to a natural key such as the order or payment ID, and keep it when you retry. The server keeps the first event with that ID. The SDKs do not generate one for you.

4. Link the event to a visit and its source

• Session: an event without session_id is stored and counted, but does not join session metrics. Pass the visit's session ID if you want the purchase inside that session.
• Sign-up source: with data-attribution on the website script, tapcub.getAttribution() returns how the visitor arrived. Send it with the sign-up form and pass it as context.campaign on trackSignup, together with the request IP and user agent.
• Email and phone: identities are hashed before storage; send them with bind, not as plain properties.

5. Verify

While integrating, use debug mode (consumer: 'debug' in the SDK, or ?debug=1): the server validates every event and stores nothing. Then send a real event and look for it in All-platform analytics › Data › Events & properties or Web analytics › Events.

Common failures

Installing the website script first? See install TapCub.

See also

• How do I import server logs?
• Send events with the HTTP API
• Create API keys