Webhook campaigns

Webhook-triggered campaigns 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 person, a webhook trigger lets you start a campaign when you receive JSON data (in any shape) from a specific source.

How it works

Normally, you trigger campaigns when a person performs an event or meets some criteria you set. This type of campaign 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 campaign, 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 a campaign to send messages in Customer.io. This is the most common use case.
  • An attributeA 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. update for a person.
  • Another service—using Customer.io as a bridge between data platforms, like what Zapier and Segment do!
sequenceDiagram Participant A as Incoming service Participant B as Customer.io Participant C as Person C->>A: Person does something in your system A->>B: Trigger webhook rect rgb(229, 254, 249) Note over B,C: Update attributes B->>B: Identify person with webhook data end rect rgb(255, 242, 248) Note over B,C: Send messages with
the Create Event Action B->>B: transform webhook data to event B->>C: event triggers campaign end

Create a webhook-triggered campaign

As a part of campaign 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 Campaigns and click Create Campaign.

  2. Select Data arrives via webhook.

    the webhook campaign trigger exposes a webhook URL
    the webhook campaign trigger exposes a webhook URL

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

  4. Click Save & Next

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

    • Create Events to trigger another campaign or add people to segments.
    • Create or Update people in your workspace.
    • Send a Batch Update to update attributes or send events for multiple people.
    • Use the Send data action to send a webhook. Your webhook forward your data to another service outside Customer.io.
      Set up your workflow actions to transform data
      Set up your workflow actions to transform data
  6. Review your workflow and Save.

 You can send Slack notifications in a webhook-triggered campaign!

Because you trigger a webhook-based campaign with data that isn’t attached to a person in Customer.io you can’t use most message types in this kind of campaign—you’d have nobody to send them to!

However, because Slack messages typically have a static destination—a channel or a specific DM—you can trigger a slack message. This provides a way to notify a group of people via Slack when you trigger your workflow.

Send event

The Send Event action lets you transform your incoming Trigger data to an event, so you can trigger messaging campaigns or add people to segments. In general, the webhook that triggers your campaign 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 people in your workspace. If your incoming webhook does not have an identifier, you can still create an event, but you’ll set a static identifier and continually create events for the same person.

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 in your webhook-triggered campaign:

  1. Drag Create 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.
    Add a create event action to your webhook-triggered campaign
    Add a create event action to your webhook-triggered 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

  1. Click Save & Next and finish configuring your webhook-triggered campaign.

Create or update a person

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 person as a part of your workflow. If the identifier matches a person in your workspace, this action updates that person; if the identifier does not match a person, this action creates a new person.

  1. Drag the Create or update person block 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 people based on an attribute in your incoming webhook.
  3. 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 person you want to find or create, and then pick a value from your incoming webhook data.
  4. Click Add attribute and set attribute values for the new person.
    • Attribute represents the name for the new attribute.
    • Value lets you select where your value comes 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 person’s attribute.
  5. Click Save Changes when you’re done, and finish your webhook-triggered campaign.

Batch update

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

flowchart LR a[incoming webhook]-->g subgraph g [Webhook-Triggered Campaign] direction LR c[batch update] c-.->|send event or
update attributes|d[matching person 1] c-.->|send event or
update attributes|e[matching person 2] c-.->|send event or
update attributes|f[matching person n] end

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

send events to multiple people with a batch update
send events to multiple people with a batch update

Liquid variables

When you create an event or set a person’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.

 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!

Trigger DataOutgoing Webhook (identify)
{
"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 campaign

When you use the Create Event or Create or Update Person actions, you can also manipulate values from your Trigger data (or 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.) 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 person’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.

 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 data with javascript
set event data with javascript
Copied to clipboard!
Is this page helpful?