Create an event

You can convert the incoming webhook for a data campaign into an event associated with a person—in any workspace within your account. This makes it easy to trigger campaigns or add people to segments based on things that happen outside of Customer.io without having to talk to a developer and write your own integration.

 You can create an event from other kinds of campaigns too!

You’ll probably create events in most data campaigns—that’s how you associate incoming data with a person. But now you can create events in any campaign, making it easy to trigger parallel campaigns. You can create an event for the current person or someone else entirely.

How it works

Data campaigns start with arbitrary data from an incoming webhook. This data isn’t associated with a person, and it can take any shape.

When you create a data campaign, you trigger your campaign based on an incoming webhook. You need to associate it with a person and re-shape your incoming data to a format that Customer.io recognizes—so that you can trigger campaigns, add people to segments, etc. This shape is called an event!

The Create Event action makes it easy to generate an event from your incoming webhook data, so that you can trigger other campaigns and organize segments as a part of your data campaign. This action even lets you send an event to another workspace, making it easy to manage people and events across your workspaces.

sequenceDiagram participant A as Person participant B as External System participant C as Customer.io A->>B: Does something B->>C: Incomming webhook C->>C: Create event Note over A,C: Your event can add people to segments or trigger campaigns C-->>C: Add person to segment C-->>C: Trigger campaign C-->>A: Response message (Optional "Thanks for your response!")

The Create Event action

To create an event, your incoming webhook must contain a value that you use to identify people. When you create an event, you associate a value in your incoming webhook with an identifierThe attributes you use to add, modify, and target people. Each unique identifier value represents an individual person in your workspace. for people in one of your workspaces. If a person with this identifier doesn’t already exist, this action will add them to your workspace.

When you create an event, you can pick from three types of values for your Event Name (the name key) and Event Attributes (contained by the data object):

To create an event from your data campaign:

  1. Drag Create Event into your data campaign workflow and click it.
  2. Set the Event Name, and then click Edit event to set up your event. The event name helps you identify this action in your workflow; it’s not the name value for the event.
    Add a create event action to your data campaign
    Add a create event action to your data campaign
  3. Use Find or add person to identify the people you want to attach events to.

    1. Select the workspace containing the people you want to attach events to.
    2. Select the type of identifier and set the identifier’s value for people in that workspace.You can identify someone from a trigger attribute or set a Static value to always send events for the same person.

  4. Set the Event Name. This is the name value in the event, and the way you’ll reference this event in campaign triggers, segments, etc.
  5. Add Event Attributes. These are the values that appear in the data object of your event. You can use these properties to filter people into different campaigns, or reference them in messages using liquidA syntax that supports variables, letting you personalize messages for your audience. For example, if you want to reference a person’s first name, you might use the variable {{customer.first_name}}..
  6. Click Done.
    Convert your incoming data to an event
    Convert your incoming data to an event

Use liquid when creating events

When you use the Liquid value type or the JSON editor, you can manipulate trigger data to fit your event using liquidA syntax that supports variables, letting you personalize messages for your audience. For example, if you want to reference a person’s first name, you might use the variable {{customer.first_name}}.. This gives you more control over the data you use in your event, by letting you modify trigger data to better support your event in Customer.io.

In liquidA syntax that supports variables, letting you personalize messages for your audience. For example, if you want to reference a person’s first name, you might use the variable {{customer.first_name}}., you access properties from your trigger data using JSON dot notation, beginning with trigger. For example, you would access the id attribute from the trigger data below using {{trigger.identifiers.id}}.

 When you reference an array or object, use | to_json

By default, liquid maps objects and arrays to strings (or an integer, where applicable). Use | to_json when you reference an object or array in your outgoing webhook to avoid errors and maintain the original shape of your trigger data!

{
  "name": "purchase",
  "identifiers": {
    "id": "abcd-1234",
    "email": "person@example.com"
  },
  "purchased_at": "Fri, 04 Feb 2022 23:49:39 GMT",
  "total": 123.45,
  "items": 2,
  "tax": 10.45
}

Liquid with arrays and objects

By default, liquid maps arrays and objects to strings (or, if an array contains only integers, liquid maps it to a single number). You need to use to_json to maintain the shape of arrays or objects in your event. Otherwise, you won’t be able to access properties inside the array or object in campaigns or segments that use your event.

With to_jsonWithout to_json
Selecting an array of objects in liquid with to_json formats the object correctly
Selecting an array of objects in liquid with to_json formats the object correctly
Selecting an array of objects in liquid without to_json results in an unusable string
Selecting an array of objects in liquid without to_json results in an unusable string

For example, if you want to create an event with the purchase array from the trigger data below, you would format your liquid like this: {{trigger.purchase | to_json}}. The to_json tag also maintains the original data type of items inside the object—strings, numbers, etc.

{
  "name": "purchase",
  "identifiers": {
    "id": "abcd-1234",
    "email": "person@example.com"
  },
  "purchased_at": "Fri, 04 Feb 2022 23:49:39 GMT",
  "total": 123.45,
  "items": 2,
  "tax": 10.45,
  "purchase": [
    {
        "product_name": "shoes",
        "sku": 1234,
        "qty": 1,
        "price": 73.00
    },
    {
        "product_name": "socks",
        "sku": 5678,
        "qty": 4,
        "price": 40
    }
  ]
}

Modify values with liquid

When you add trigger data to your event with liquid, you can modify or even transform values to better support the things you want to do in Customer.io

See the liquid tag list to see all the ways you can modify these values. But, using the event above, here are a few quick examples of what you can do:

Reformat the purchase_at ISO date-time to a Unix timestamp using date %s.

"created_at": "{{ trigger.purchased_at | date: %s }}"

outputs 1644018579

Prepend or append the event name with a static value with append or prepend.

"name": "{{trigger.name | prepend "online_" }}"

outputs: online_purchase

Map the product names from the purchase array to a single key using map.

"products_purchased": "{{trigger.purchase | map: 'product_name'}}"

outputs: shoes, socks

Use JavaScript when creating events

You can manipulate values that you set in your event with JavaScript. When you use the JavaScript option, you’ll either produce a return statement for each data attribute in your event, or switch to the JSON editor and return an object containing all your event data properties. You can set properties from any source available in your campaign—trigger data, attributesA key-value pair that you associate with a person—like their name, the date they were created in your workspace, etc. Use attributes to target people and personalize messages., event properties, snippetsA common value that you can reuse with Liquid in messages and other workflow actions—like your company address. You can store Liquid inside a snippet, making it easy to save and reuse advanced values and statements across your messages., etc.

For example, if you wanted to access a person’s id from the object we used in our Liquid example above, you would use return triggers.identifiers.id;.

See our JavaScript quick reference guide for more examples to help you take advantage of JavaScript in your workflow.

 You can’t use Liquid inside JavaScript

When you use the JavaScript option, you must manipulate values with JavaScript. If you try to return a snippet value that contains Liquid, you’ll receive an error.

set event values using JS
set event values using JS
Copied to clipboard!
Is this page helpful?