Skip to main content
Events are the raw signal Spotzee uses to trigger journeys, build behavioural segments, and drive reporting. Send events from your backend whenever a user does something worth marketing on: completes a checkout, opens a feature for the first time, abandons a cart, or hits a usage milestone.

​
What you’ll build

A backend service that:
  1. Captures domain events as they happen.
  2. Forwards each one to Spotzee with the user’s external_id.
  3. Batches when traffic is bursty and retries on failure.

​
Prerequisites

You’ll need a sk_ project key with write access. The browser-side equivalent uses a pk_ publishable key. See Authentication.

​
Walkthrough

1

Pick stable user IDs

Identify each event with the same external_id you used to sync the user. If the user is anonymous (a not-yet-signed-up visitor), use anonymous_id instead. Spotzee stitches the two together when the user later identifies.
2

Choose an event name

Use snake_case verbs: order_placed, subscription_renewed, feature_enabled. Stick to a small catalogue. Every event you create is a hook journeys and segments can depend on, so churn in event names breaks downstream automation.
3

Send events

POST /events accepts a JSON array of one to 100 events per call. Even when sending a single event, wrap it in an array.
Per-item errors come back in the response. Items that succeeded are committed.
4

Batch when you can

For high-volume sources (queue consumers, ETL jobs, replay scripts), pack up to 100 events into a single call:
5

Add user details alongside the event (optional)

If the event also reveals new user information (say, a checkout that finally captures the user’s email), include a user block. Spotzee upserts the user in the same call, so a downstream segment that depends on email IS NOT NULL fires correctly.
The user block accepts email, phone, timezone, locale, and a data object for custom attributes.
6

Retry safely on failure

Network blips happen. Add an Idempotency-Key so a retry doesn’t double-count an event in reporting. A deterministic key (order_placed:ord_42) is easier than a UUID for replay scenarios. See Idempotency.

​
Pitfalls to avoid

Don’t put PII in the event name. Names are searchable, indexed, and shown to operators in the UI. Keep them generic; put the variable bits in data.
  • Don’t send “view” events from your backend unless you have a real reason to. Page views belong in browser-side tracking with a pk_ key. Backend events should reflect domain transitions: orders, subscriptions, status changes.
  • Don’t churn the schema. If you add a field to data, keep it. Removing it breaks segments and journeys that already depend on it.
  • Don’t forget Spotzee-Version. It’s optional, but pinning a version makes your event payload’s behaviour predictable across releases. See API versioning.

​
Reference