Events - SeerStack

Events are the immutable history of what happens in your application. An event consists of a name, a timestamp, and a JSON payload.

Event Structure

A valid event object contains the following fields:

Field	Type	Required	Description
`name`	string	Yes	The name of the event (e.g., `signup.completed`).
`user_id`	string	No	The ID of the user who performed the action.
`data`	object	No	Arbitrary JSON object with event properties.
`timestamp`	string	No	ISO 8601 timestamp. Defaults to `now`.

Sending Events

Use the events.capture method to record an event.

TypeScript
Ruby
cURL

import Seerstack from 'seerstack';

const client = new Seerstack({
  apiKey: process.env['SEERSTACK_API_KEY'],
});

await client.events.capture({
  name: 'invoice.paid',
  user_id: 'cus_8374',
  data: {
    invoice_id: 'inv_993',
    amount: 2000,
    currency: 'usd'
  }
});

require "seerstack"

seerstack = Seerstack::Client.new(
  api_key: ENV["SEERSTACK_API_KEY"]
)

seerstack.events.capture(
  name: "invoice.paid",
  user_id: "cus_8374",
  data: {
    invoice_id: "inv_993",
    amount: 2000,
    currency: "usd"
  }
)

curl -X POST https://api.seerstack.com/capture \
  -H "Authorization: Bearer $SEERSTACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "invoice.paid",
    "user_id": "cus_8374",
    "data": {
      "invoice_id": "inv_993",
      "amount": 2000,
      "currency": "usd"
    }
  }'

Naming Conventions

We recommend using a noun.verb syntax for your event names. This keeps your data organized and easy to search.

Event names starting with $ are reserved for SeerStack system events like $pageview, $click, and $rageclick. Avoid using $ prefixes for your own custom events.

Good

project.created
user.signup
payment.failed

Bad

created project
User Clicked Signup Button
fail