Server-side events
Some events are better sent by your server than by a browser: a payment, a cancelled subscription, a renewal. A browser can neither block nor fake them, and they can carry details that a page should not see. Your server sends them to POST /api/server-events with the project’s secret key.
When to send from the server
Section titled “When to send from the server”Send an event from the server when:
- it happens on the server, such as a webhook from your payment provider;
- it must be counted even when the visitor uses an ad blocker or closes the tab;
- it must not be faked by someone who copies your public key.
Each server-side event belongs to a signed-in user of your app. For what anonymous visitors do in the browser, use track().
The secret key
Section titled “The secret key”Open the project’s Settings, then the Your server tab. The owner and admins can see it. Members cannot.
- The secret key (
sk_…) is hidden until you select Show. Then you can copy it. - Below it, “Send events from your server” has an example request to copy.
- Keep the key on your server, for example in the
OTTERTRAIL_SECRET_KEYenvironment variable. Never put it in a page or in your repository. The endpoint sends no CORS headers, so a page cannot even read its answers. - If the key ends up where it should not, replace it in the Danger zone tab. Servers with the old key are refused at once.
Send an event
Section titled “Send an event”curl https://analytics.example.com/api/server-events \ -H "Authorization: Bearer $OTTERTRAIL_SECRET_KEY" \ -H "Content-Type: application/json" \ -d '{ "v": 1, "environment": "production", "release": "[email protected]", "events": [{ "id": "8c1f0a52-3d4e-4f60-9b7a-1c2d3e4f5a6b", "name": "subscription_started", "occurredAt": 1794823396705, "userId": "42", "path": "/checkout", "properties": { "plan": "team" } }] }'id: a new UUID for each event.name: any name except the tracker’s own:pageview,engagement, andvitalsare refused.occurredAt: when it happened, in milliseconds since 1970, by your server’s clock.userId: required. Your app’s ID for the user, the same ID the browser sends (see Name signed-in users). It needs no signature: only your server has the secret key.path: optional. A path that starts with/. Without one, the user’s page shows the event by its name only.properties: optional, with the same rules as in the browser.environmentandrelease: optional, for every event of the request. Without an environment, the events count asproduction. See Environments and releases.
A request holds 1 to 50 events and at most 64 KB. The whole format and every answer are in the HTTP API reference.
Where the events show
Section titled “Where the events show”- The user’s page, under Users: the event in the user’s activity, with its name, properties, and path. See The Users page.
- Product analytics: the Events tab counts the event, with its users. Its Visitors column stays 0, because a server-side event has no visitor. A funnel counted by users, and the retention report, include it too. See Funnels and Retention.
They do not show in web analytics, which counts what browsers send, and they do not count toward goals, which count visitors. No location, browser, or device is recorded: the request comes from your server, not the user’s device.
Retries and timestamps
Section titled “Retries and timestamps”The instance trusts your server’s clock, so keep it right.
- An
occurredAtmore than 5 minutes in the future is refused with 400. - An event that happened more than 24 hours ago is not stored. The answer counts it in
tooOld. - The answer is 202 only after the events are written. Its body is
{ "stored", "tooOld" }.
When a request fails, send it again only after 429 or 503, and after the seconds in Retry-After. Other errors will fail again.
A retry is stored once only when it sends the same id and the same occurredAt as the first attempt. Make both when the event happens, keep them with the event, and send them unchanged on every attempt. A sender that stamps the time again on each attempt stores its retries twice.
Limits
Section titled “Limits”- Requests from each IP address: a burst of 600, then 50 a second.
- Server-side events share the project’s event budget with its browser events. A flood of browser events, which anyone with the public key can send, can hold your server’s events back too (429, to send again).
- The spam and bot checks do not apply: not the data centers, blocked addresses, referrer spam, the limit of events per client address, or the daily cap per visitor.
See Limits for the rest.