New Guide: Running Background Jobs with Prisma ORM + TypeScript
Join our Discord
Sign up for free

Format and structure

Events are always JSON, and must contain the fields name (a string) and data (an object).

You can optionally add user information within user (an object), version events with the v field (a string), and set their timestamp with the ts field (an int, millisecond precision).

Events ingested into our system have a specific format. Here is the entire payload, though only name and data are required:

json
{
"name": "ticket.updated",
The event name is required.
"data": {
"ticket_id": 189325,
"comment": "Thanks for sending me the return label!",
"status": "open"
},
Data is also required.
"user": {
"external_id": 83561,
"email": "test@example.com"
},
"v": "2021-09-15.01",
"ts": 1632232002369
}

Fields

These are the fields which you can provide in an event:

  • name: (required) The event name as a string. We recommend a simple format of "noun.action", eg "payment.succeeded", "email.sent", "post.viewed"
  • data: (required) An object containing any data pertinent to the event
  • user: (optional) An object containing information relating to the user which the event belongs to. For example, a “payment.succeeded” event should contain information on the user who paid.
  • v: (optional) A string representing the event version. We recommend the format “YYYY-MM-DD.XY”, where XY increments with changes. This allows you to see the implementation date easily, and allows for infinite changes
  • ts: (optional) An int representing the milliseconds since the unix epoch at which this event occurred. If this is blank we default to the time the event was received. This is useful when backfilling contact attribute history

Why this format?

Each field represents unique information and has been chosen to increase flexibility powering our system. We store a unique type schema for each version of each event, allowing you to adapt systems over time without changing event names.

The timestamp allows you to backdate events when importing into our systems. This is important when adding user information to our system, as the user attributes are valid from the time of the event. For more information, see user identification within events.

The payload allows us to:

  • Automatically detect event anomalies - events which do not contain information typically included within a specific version
  • Create workflows that are triggered off of both event names and versions
  • Adapt to changes in your systems over time, without renaming events
  • Correctly specify users for audit trails without need for persistent tracking