Server-side event tracking means your backend sends an event over HTTPS when something happens that the browser cannot see, such as a payment, a webhook or a finished job. With JustOneCX you POST to /ingest/events/track with your Secret key and the person's userId. The event then counts in analytics, segments and funnels like a browser event.
When should you track events on the server?
Use the server when the browser cannot prove the event. A browser can be closed, blocked or edited by the user. Your server knows what really happened.
Good cases:
- A payment succeeded.
- A webhook from another service fired.
- A background job or import finished.
- A subscription changed plan.
Keep using track() in the browser for clicks and page views. Server events add the facts the page cannot see. If you have not decided which event matters most, read the activation event guide.
How do you send an event?
Send a POST request to https://api.justonecx.com/ingest/events/track. You authenticate with your Secret key, never the Public key.
| Field | Type | Notes |
|---|---|---|
userId |
string | Your own user id, the one you pass to identify(). Recommended. |
visitorId |
string | One browser's visitor id. Use it only if you have it. |
accountId |
string, optional | Links the person to an account, like group(). |
eventName |
string | For example subscription_upgraded. |
properties |
object, optional | Strings, numbers, booleans or null. |
Send userId or visitorId. Both are fine. With userId, the event goes to that person's profile across all their browsers. If the person has never opened your app, a profile is created and joins the later identify() for the same id. A successful call returns 204 and no body.
Here is the Node.js version, for Node 18 or later.
await fetch("https://api.justonecx.com/ingest/events/track", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.JUSTONECX_SECRET_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
userId: String(user.id),
eventName: "invoice_paid",
properties: { amount: 4900 },
}),
});
And the same call with curl.
curl -X POST https://api.justonecx.com/ingest/events/track \
-H "Authorization: Bearer $JUSTONECX_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"userId": "user-123", "eventName": "subscription_upgraded", "accountId": "acme", "properties": {"plan": "pro"}}'
The docs also show Python, Ruby, PHP and Go. Any backend language that can send an HTTPS request works. See Server events.
Where does the Secret key live?
The Secret key starts with sk_. It belongs in your server environment as JUSTONECX_SECRET_KEY. Put it in your hosting dashboard, a server .env file or a CI secret. Add the empty name JUSTONECX_SECRET_KEY= to .env.example so the next developer knows it exists.
Never put the Secret key in client code, a mobile app or a public repository. Do not paste it into a chat or into an AI assistant. You copy it from Settings → Developers → Secret key into your own server environment. The full key is shown once, when you generate it.
A leaked Secret key lets someone send fake events and forge user identities. Treat it like a password, and rotate it if you think it leaked. One key does two jobs: it authenticates event calls, and it signs userHash for identity verification. If you rotate it, your server must use the new key for both. See the Keys page in the docs.
Which userId should you send?
Send the same id you pass to identify() in the browser. Then the server event lands on the same profile as the visitor. If the browser sends user-42 and the server sends 42, you get two people. Convert the id to a string the same way in both places. Read identify users with the SDK for the browser side.
How do server-confirmed tour steps work?
A tour step can finish on an event instead of a button click. In the step's Pages, targets and completion section, pick What completes this step, then choose An event. You give the event name and, optionally, properties that must match, such as plan=pro.
You then choose where the event may come from.
- From the browser or your server. A
track()call on the page finishes the step at once. An event your server sends does too. - Only from your server (confirmed). Use it for things the browser cannot prove, such as a successful payment. A browser
track()call never finishes this step.
For a confirmed step, the widget asks the server where the person is every 10 seconds while the step is open. Allow up to about 10 seconds after your server event. An event only moves a person who is on that step. A tour that is not started, or is on a different step, ignores it.
This is useful for a tour that says "Add your card" and should only move on when the payment really went through.
What errors can come back?
| Status | Meaning |
|---|---|
400 |
The body has neither userId nor visitorId, or a field is too long or the wrong type. |
401 |
The Secret key is missing, wrong or was rotated. |
429 |
Too many calls for this key (3000 per minute). Slow down and retry. |
If you get 401 after a rotation, deploy the new key to your server.
How do you check that an event arrived?
Open your event log in the dashboard, or ask your AI assistant. The MCP server has an events tool that lists the raw event log, newest first, and can filter by event name and source. It is read-only.
Frequently asked questions
Do server events count in analytics?
Yes. Server events count toward analytics, segments and funnels like browser events.
Can I use the Public key for server events?
No. You authenticate with your Secret key. The Public key is for the browser.
What happens if the user never opened my app?
If you send a userId for someone who has never opened your app, a profile is created. It joins the later identify() call for the same id.
What is the rate limit?
3000 calls per minute for each key. A 429 response means slow down and retry.
See how it works in the live demo.