Skip to main content

Event format

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).

This format is simple and powerful. Next up, look at the user field and how to send events.

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

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

Fields

The fields are as follows:

  • 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?

Our event format is reduced to the simplest elements possible. Each field represents unique information and has been chosen to increase flexibility powering our system.

For example, in most systems, events are not versioned or are versioned as an afterthought. By including versions as a first-class citizen, we can:

  • 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

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.