Events

An event is a structured record of something that happened in your application.

Event structure

Every event is a record with the following fields:

  • type (required): a string naming what happened
  • userId (optional): the user who triggered the event
  • groupId (optional): the group the event belongs to
  • source (optional): where the event came from
  • data (optional): a free-form key/value object of structured information
  • context (optional): a dictionary of environment metadata such as browser, OS, device type, screen, viewport, URL, path, referrer, timezone, locale, country, and IP
  • tags (optional): arbitrary metadata

The server enriches each event with ip, locale, and country before storing it.

Event types

The event type is a string that describes what happened. Vanta uses a dot-separated convention so that types read as a hierarchy:

  • user.signup
  • checkout.completed
  • job.processed
  • error

Naming events

Prefer dot-separated hierarchical names. They group naturally in analytics and make it easy to answer questions like “how many checkouts completed last week?”

Sending events

Send an event with vanta.track():

typescript
import { Vanta } from '@vanta-dev/node'

const vanta = new Vanta({
  apiKey: process.env.VANTA_API_KEY,
})

await vanta.track({
  event: 'user.signup',
  userId: 'user_123',
  data: {
    plan: 'pro',
    referral: 'docs',
  },
})

The type field in the stored record comes from the event option you pass to track().

Immutability

Events are immutable after creation. You cannot edit or delete an event once it is stored, which keeps your analytics history stable and trustworthy. If you need to correct a mistake, record a new event rather than trying to change an existing one.