Webhooks - Getting Started

A custom webhook can pass data to just about any public API on the internet. You can use it to send a text message, update a CRM or take just about any action on a customer that you’d want to do.

With a little trial and error, you should be able to connect Customer.io to another service you’re using. This guide will give you some basics to help you get started.

Creating a webhook action

In the workflow for a campaign, you can click to Add workflow item

Webhook action - Add workflow item

…and choose a webhook from the resulting modal:

Webhook action - Add webhook

After adding a Webhook, click Add Request to go into the message composer.

Add a webhook request

HTTP Request Types

Customer.io webhook actions support 4 common HTTP request types for RESTful APIs:

  • GET
  • POST
  • PUT
  • DELETE

The one you use is dependent on what the API you’re using is expecting. Post is most likely to be used and is the default.

Request URL

Next to your request type you will add the request URL that you want us to send the data to.

If your API requires Basic Authentication, you’ll add the username and password to the request like: https://user:pass@api.example.com

Headers

You can customize the headers that Customer.io sends with each request in order to support things like:

  • Specifying the Content-Type
  • Supporting other types of Authentication
  • Setting other specific headers required for a specific API

Content-Type

By default, we pre-fill: Content-Type: application/json

Other example Content-Type values are:

  • x-www-form-urlencoded
  • text/plain
  • text/xml

Note, we recommend working with APIs using Content-Type: application/json for readability whenever possible.

Structuring content for a webhook (JSON)

If you’re using Content-Type: application/json, you’ll want to make sure you’re using fully formed JSON.

A good place to test this is:

http://jsonlint.com/

A simple example for valid JSON is:

{
    "id":"1",
    "email":"win@customer.io"
}

You’d create something like that by putting this text in to the editor:

{
    "id":"{{customer.id}}",
    "email":"{{customer.email}}"
}

Example Webhook Composer

Then clicking “Preview”

A slightly more advanced example is:

{
    "customer":
    {{ customer | replace: "=>", ":"}}
}

That will output the entire customer object in JSON format.

Structuring content for a webhook (Form encoded)

If you want to send a form encoded webhook, you’ll set the Content-Type header as: x-www-form-urlencoded

Then, the body needs to be valid form encoded text. Something like:

id=1&email=win@customer.io&custom_attribute=value

You’d create something like that by putting this text in to the editor:

id={{customer.id}}&email={{customer.email}}&custom_attribute={{customer.another_attribute}}

The downside of form encoded is that it’s a bit harder to structure and read since there are no line breaks and separation other than the “&” characters that join everything together.

Timeouts and Failures

We have a 4 second timeout and if we don’t get a successful (200) response in that period, or if anything but a 200 success code is returned, Customer.io will retry sending the notification several times with exponential backoff. We keep retrying up to a max of 10 times over a period of approximately 7 hours.

Testing your requests

If you’d like to test the format of your requests before pointing them at the correct API, you could use a service like Webhook.site. A URL is automatically generated on Webhook.site which you then paste in to Customer.io as the request URL.

More ideas & examples

If you’re looking to see some real world examples, take a look at some of our walk throughs.