Skip to main content
Send events from your backend when the browser or the game is not the right place: a webhook handler, a background job, a Cloudflare Worker or a game server. Server events go to the same endpoint as web and game events, POST /v0/events. Each event has channel: 'server', and the request uses the project secret key.

Create the secret key

  1. Open your project and go to Settings > General > Credentials.
  2. Click Create secret key. You must be an owner or admin with an MFA session.
  3. Copy the key. It starts with ua_sk_ and is shown only once. Untitled Analytics stores only a SHA-256 hash and a short display prefix.
You can rotate the key (the old key stops working at once) or revoke it in the same place. Each change is in the audit log (project.secret_key_created, project.secret_key_rotated, project.secret_key_revoked).
The secret key is for your backend only. Never put it in a web page, a game build or an app build. Keep it in a server-side secret store. A request with an Origin header (a browser) and a secret key is refused with 403 SECRET_KEY_FROM_BROWSER.
The publishable key cannot send server events, and the secret key cannot send web or app events. See authentication.

Send events

Send the secret key as Authorization: Bearer. Do not send an x-publishable-key header in the same request.
Node.js
See the API reference for every field and response.

Rules

  • Every event in the batch has channel: 'server'. A batch that mixes server events with web or app events gets 400 MIXED_CHANNELS.
  • Types are track and identify only.
  • Up to 100 events in one request, and at most 256 KB.
  • user_id alone is enough. You can also send anonymous_id, or both.
  • message_id and original_timestamp are optional. Old timestamps are allowed, so you can backfill. A timestamp more than 5 minutes in the future is refused.
  • Server events have their own rate limit bucket, so browser traffic does not use up the quota of your backend.

Context

The request comes from your backend, so its IP address and user agent are not the player’s. The collector does not use the request IP or the request user agent for server events. Your backend can forward the player’s values in context: All context fields are optional.

Join server events to players

  • user_id only: the event gets a stable project-scoped ID, so the user counts as one visitor.
  • anonymous_id only: forward the ID of the browser or game (analytics.getAnonymousId() in the web SDK) to join the event to that visitor.
  • Both: the event links that browser or game to the user, so earlier anonymous activity joins the user’s profile.

Session ID of the client

Send the session ID of the client with your server call. The event is then in the visitor’s session, also when your backend sends it late (for example after a payment webhook, hours or a day later). A server event adds its event and revenue to the session and does not change the session duration: the duration comes from the events that the website or the game sent.
  1. The client reads its two IDs and sends them with its request to your backend: getAnonymousId() and getSessionId() in the web SDK and the Node SDK app mode, get_anonymous_id() and get_session_id() in Godot, AnonymousId and SessionId in Unity.
  2. Your backend puts them on the event as anonymous_id and session_id.
  • A session_id needs the anonymous_id of the same client: a session belongs to one anonymous_id.
  • A server event without a session_id stays valid. It joins the session of the same anonymous_id that is active at that time, or one that starts in the next 30 minutes. If there is none, the event is in no session that counts. It still counts as an event and as revenue.
  • The rule that an event needs a session ID is for website and game events (the publishable key). It does not apply to server events.

Retries

Set a message_id (a UUID) on each event. If you send the same event twice, reports count it once. If you omit it, the collector creates one.

Errors

See errors for the full list.

Reports

Server events appear in every event report, on profiles, in the Users list, retention, funnels and breakdowns. Their origin channel is server. They have no acquisition channel, so channel reports show them as Direct.