This page is part of the Customer.io documentation. For the complete documentation index, see llms.txt.

15

Send events from your workflow

You can create an event within an automation through the Send event block. This makes it easy to trigger other automations or add profiles to segments. For webhook-triggered automations, this makes it easy to reshape and associate data from an outside source with profiles in your workspace, all without having to talk to a developer or write your own integration.

An event consists of a name and a data object. The name is typically how you’ll select an event, and you can further filter profiles based on data in the event. You can use properties in the data object to personalize automations 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}}. in the format {{event.<property>}}.

{
  "name": "my_event",
  "data": {
    "a_value": "that-I-use-in-liquid"
  }
}

A Send event action has a size limit of 100 KB.

How it works in most automations

As long as your automation isn’t triggered by a webhook—i.e. it begins when a profile performs an event, matches attributesA key-value pair that you associate with a person or an object—like a person’s name, the date they were created in your workspace, or a company’s billing date etc. Use attributes to target people and personalize messages. conditions, etc—you can send an event for the profile currently in automation, or another profile entirely. You’ll send your new event from values in the eventSomething that a person in your workspace did. Events can trigger automations, add people to segments, etc, and you can use properties from events to personalize messages. that triggers your automation or customer attributes.

If you want to send an event for another profile, you’ll need a value representing that other profile either in the event that triggered the current automation, or stored as an attributeA key-value pair that you associate with a person or an object—like a person’s name, the date they were created in your workspace, or a company’s billing date etc. Use attributes to target people and personalize messages. on the profile currently in the automation. If the profile with this value doesn’t exist, your event will create them!

Send an event

When you use the Send Event action, you can pick from different types of values for your Event Name (the name key) and Event Attributes (contained by the data object):

• Static value: a value that is the same in every event
• Customer attribute: a value associated with the profile in the automation
• 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}}.: use liquid to modify customer or event attributes to fit your event—like reformatting a date value or appending a string to your event’s name.
• JavaScript: use JS to modify customer or event attributes to fit your event.
• Event attribute: a value from the data object of the event that triggered the automation (if applicable)
• Trigger object attribute: a value from the object that triggered the automation (if applicable) - To see a preview of the payload, make sure you select a profile from the sample data on the left who has a relationship to the object.
• Trigger relationship attribute: a value from the relationship that triggered the automation (if applicable) - To see a preview of the payload, make sure you select a profile from the sample data on the left who has a relationship to the object.

To send an event in an automation:

1. Drag Send Event into your 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.

   

   
3. Select the person you want to send an event for. By default, this is the person in the current campaign.

   If you select Someone else, you can pick the Workspace your other profile belongs to, and you’ll need to select the value representing their identifier.

   

   
4. Set the Event Name. This is the name value in the event, and the way you’ll reference this event in automation 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 profiles into different automations, 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.

How it works in a webhook-triggered automation

A Webhook-triggered automation is an automation that begins when you receive an incoming webhook. This incoming webhook is not directly associated with a profile in your workspace. That’s often why you’ll create a new event: to re-shape and associate your incoming webhook data with a profile in your workspace to trigger messages, add a profile to segments, etc.

Your incoming webhook should contain a value that you use to identify profiles. When you create an event, you’ll 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 profiles in one of your workspaces. If a profile with this identifier doesn’t already exist, this action will add them to your workspace.

Send an event from a webhook-triggered automation

When you create an event, you must specify an Event Name (the name key) and Event Attributes (contained by the data object). Each of these fields can be one of four types:

• Static value: A value that is the same in every event.
• Trigger attribute: A property from your Trigger data. You can start typing to find a key in the incoming data or click the value in the Trigger data.
• 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}}.: Use liquid to modify trigger attributes to fit your event—like reformatting a date value or appending a string to your event’s name.
• JavaScript: Use JavaScript to modify trigger attributes to fit your event—like reformatting a date value or appending a string to your event’s name. Use JavaScript over liquid if you want to modify incoming JSON.

To send an event from your webhook-triggered automation:

1. Drag Send Event into your workflow and click it.
2. Set the Event Name. The event name helps you identify this action in your workflow; it’s not the name value for the event.
3. Click Add event to set up your event.
4. Under Who do you want to update?, select the Workspace containing the profiles you want to attach events to.

   

   
5. Select the type of Identifier and set the identifier’s value for profiles in that workspace. You can identify someone from a trigger attribute, liquid, or JavaScript. Set a static value to always send events for the same profile.
6. Set the Event Name. This is the name value for the event that you’ll reference outside of this automation in other automation triggers, segments, etc.
7. Add Event Attributes. These are values that appear in the data object of your event. You can use these properties to filter profiles into different automations 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}}..
8. Save your changes and click Done. Now you can finish building your webhook-triggered automation.

Use liquid to modify event properties

The Liquid value type (or the JSON editor) lets you manipulate 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}}.. When using liquid, you access properties using JSON dot notation, beginning with the type of data you’re working with:

• Customer attributesA key-value pair that you associate with a person or an object—like a person’s name, the date they were created in your workspace, or a company’s billing date etc. Use attributes to target people and personalize messages. begin with customer. If you wanted to access a profile’s ID, you would use {{customer.id}}.
• Events begin with event. If you wanted to access a property in an event’s data object called id, you would use {{event.id}}.
• Objects begin with objects. If you wanted to access a property for an object, you would use {{objects.<object_type>[#].<attribute>}}.
  • Objects trigger syntax would be {{trigger.<object_type_singular>.<attribute>}}.
• Relationships begin with objects. If you wanted to access a property in a relationship, you would use {{objects.<object_type>[#].relationship.<attribute>}}.
  • Relationship trigger syntax would be {{trigger.relationship.<attribute>}}.
• Webhook trigger data begins with trigger. For example, you would access the id attribute from the trigger data below using {{trigger.identifiers.id}}.

{
  "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, concatenated 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 automations or segments that use your event.

With to_json	Without to_json

For example, if you want to send 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
    }
  ]
}

Examples

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 to modify event properties

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 automation—trigger data, attributesA key-value pair that you associate with a person or an object—like a person’s name, the date they were created in your workspace, or a company’s billing date etc. Use attributes to target people and personalize messages., event properties, snippetsReusable content, like a company address, that you can reference with a liquid key across your messages., etc.

For example, if you wanted to access a profile’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.