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

10

Webhook automations

Webhook-triggered automations let you use your JSON data in Customer.io, without having to reshape it using Zapier or another product first. Where our traditional workflows trigger based on a profile, a webhook trigger lets you start an automation when you receive JSON data (in any shape) from a specific source.

How it works

Normally, you trigger automations when a profile performs an event or meets some criteria you set. This type of automation lets you use webhooks to trigger workflows when you receive data from an external source. This video helps explain how it works:

When you set up a webhook-triggered automation, Customer.io generates a Webhook URL. You’ll provide this URL to the service or platform that you capture data from and set up rules determining when that service or platform will call your webhook, sending data to Customer.io. The data that your service or platform sends to Customer.io can take any JSON shape—arrays, objects, etc. As a part of your workflow, you’ll transform the incoming data to fit your needs.

You might use a webhook to capture data from an external service and convert it to:

• An event that triggers an automation to send messages in Customer.io. This is the most common use case.
• 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. update for a profile.
• Another service—using Customer.io as a bridge between data platforms, like what Zapier and Segment do!

Reference customer attributes

You cannot reference existing customer attributes in webhook-triggered automations because profiles aren’t the subject of the automation: the webhook is. The automation acts on the incoming webhook data, so there’s no profile/customer to reference. Any attempt to reference customer data will return "" (or undefined when using JavaScript) within a Create/Update Profile action.

For example, the following Liquid is written to return the customer.custom_attribute value and append trigger.custom_attribute, or simply use the trigger.custom_attribute value if there is no value stored at customer.custom_attribute.

{% if customer.custom_attribute == blank %}{{ trigger.custom_attribute }}
{% else %}
{{ customer.custom_attribute | append: trigger.custom_attribute }}
{% endif %}

However, within a webhook-triggered automation, this Liquid will only return trigger.custom_attribute, regardless of the customer’s custom_attribute value.

You can use a Create/Update Profile action within the webhook-triggered automation to set attributes for profiles based on a match with the incoming webhook. You just won’t be able to retrieve the current attribute values.

Why can’t I send an email or message in my automation?

In most automations, a profile is the subject of the journey through your workflow. But in a webhook-triggered automation, the incoming webhook is the subject of the automation. We don’t know who (if anybody) your data is meant to represent. This means that you can’t send a message from a webhook-triggered automation because there’s no profile to send a message to.

But you can associate data from your webhook with a profile in your workspace and trigger a secondary automation that sends messages to a profile—as long as there’s a value in your webhook that represents a profile like an ID, email address, phone number, etc.

If your incoming webhook has this kind of data, you can use the Send Event action. This lets you transform your incoming webhook data into an 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. associated with a profile. This event can trigger downstream automations, so you can send messages to profiles based on your incoming webhook data.

Create a webhook-triggered automation

As a part of automation setup, you’ll receive a webhook URL that you need to provide to the external service that you want to capture data from. Before you begin, make sure that you have access to the service you want to capture data from, and that that service can send webhooks.

1. Go to Automations and click Create Automation.

2. Click Webhook.

   

   

3. Copy the Webhook URL and provide it to your external service. If possible, trigger the webhook; this sends representative data that you can use when setting up your automation.

4. Click Save & Next.

5. Set up your workflow. From here you can:

   • Create Events to trigger another automation or add profiles to segments.
   • Create or Update Profiles in your workspace.
   • Send a Batch Update to update attributes or send events for multiple profiles.
   • Use the Send data action to send a webhook. This forwards data to another service outside Customer.io:

     

     

6. Click Next at the top right.

7. Review your workflow, then click Start Automation at the bottom of the page.

Send event

The Send Event action lets you transform your incoming Trigger data to an event so you can trigger messaging automations or add profiles to segments. In general, the webhook that triggers your automation should contain an identifierThe attributes you use to add, modify, and target people. Each unique identifier value represents an individual person in your workspace., like an email or ID, so you can create events for profiles in your workspace. (If your incoming webhook does not have an identifier for a profile, you can still create an event, but you’ll have to set a static identifier and update the same profile everytime this automation is triggered.)

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 create an event in 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.

Create or update a profile

If your incoming webhook contains an identifierThe attributes you use to add, modify, and target people. Each unique identifier value represents an individual person in your workspace.—like an email or ID—you can create or update a profile as a part of your workflow. If the identifier matches a profile in your workspace, this action updates that profile; if the identifier does not match a profile, this action creates a new profile.

1. Drag Create or Update Profile into your workflow.
2. Give the action a Name and click Add Details. You can also set Action Conditions if you want to limit when you create or update profiles based on an attribute in your incoming webhook.

   

   
3. Select the workspace you want to add or update profiles in.
4. Select the type of identifierThe attributes you use to add, modify, and target people. Each unique identifier value represents an individual person in your workspace. for the profile you want to find or create then pick a value from your incoming webhook data.
5. Click Add attribute and set attribute values for the new profile.
   • Attribute represents the name for the new attribute.
   • Value lets you select where your value comes from and the value itself. For example, if you want to use an event property as a new attribute value, you’ll select event attribute and then the specific attribute in the event that you want to set as a profile’s attribute.
   • Keep in mind, you cannot reference customer attributes in webhook-triggered automations.
6. Click Save Changes when you’re done, and finish your webhook-triggered automation.

Batch update

Other actions in a webhook-triggered automation assume a one-to-one relationship between your data and a profile. A batch update lets you associate your incoming data with a group of up to 1000 profiles. For example, if multiple profiles can belong to an account and you trigger your webhook-based automation when the account status changes, you can use a batch update to associate the new account status with all the profiles in your workspace belonging to that account.

The batch update action works much like a Send event or Create or update profile action, except that you’ll set criteria determining the group of profiles you want to set attributes for, or send events to. See the batch update page for help setting up a batch update.

Liquid variables

When you create an event or set a profile’s attributes, you can manipulate values from your Trigger data with 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 you use liquid, you’ll reference incoming data in the trigger object. For example, you would access the id from the trigger data below using {{trigger.identifiers.id}}.

You can also use liquid to modify the trigger data. You might want to do this if you need to convert timestamps, append values, or access a specific set of values from an array. See the liquid tag list for a list of ways you can transform 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,
"purchase": [
  {
      "product": "shoes",
      "sku": 1234,
      "qty": 1,
      "price": 73.00
  }
  {
      "product": "socks",
      "sku": 5678,
      "qty": 4,
      "price": 40
  }
]
}

{
  "email": "{{trigger.identifiers.email}}",
  "last_purchased_at": "{{trigger.purchased_at | date: %s}}",
  "last_purchased": "{{trigger.purchase | map product}}"
}

Use JavaScript in your webhook-triggered automation

When you use the Create Event or Create or Update Profile actions, you can also manipulate values from your Trigger data (or snippetsReusable content, like a company address, that you can reference with a liquid key across your messages.) with JavaScript rather than Liquid. Select JavaScript as the value type, and write return statements for your attribute or event data.

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