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:
"comment": "Thanks for sending me the return label!",
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.