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 contact 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 contact’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 contact IDs

Identify each event with the same external_id you used to sync the contact. If the contact is anonymous (a not-yet-signed-up visitor), use anonymous_id instead. Spotzee stitches the two together when the contact 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.
A 204 No Content response means the batch was accepted for asynchronous processing. It does not return per-item processing results or confirm that every event has finished processing.
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 contact details alongside the event (optional)

If the event also reveals new contact information (say, a checkout that finally captures the contact’s email), include a user block. Spotzee upserts the contact 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. The profile update happens during event processing, after the batch is accepted.
6

Retry safely on failure

Keep a stable identity for each logical event in your own integration. Include an Idempotency-Key for deployments where enforcement is enabled, but do not assume that the header alone prevents duplicate event occurrences. See Idempotency for availability and replay limits.

​
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