Webhooks - Getting Started

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, you can choose a Webhook item and drag and drop it into your campaign. After doing so, click the item to edit it, then click Add Request to go into the message composer.


HTTP Request Types

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

  • GET
  • POST
  • PUT

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


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


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:


A simple example for valid JSON is:


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



A slightly more advanced example is:

    {{ 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:


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


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.

Processing Speed

Webhook actions for campaigns are sent using the same queue as our email deliveries, which handles a maximum of 600 concurrent requests as quickly as possible. This maximum throughput is shared with other customers on the same shard as your account, so you may not see the maximum throughput for your requests, especially during peak times. The actual amount will depend on system load at the time the webhook notifications are being sent.

Timeouts and Failures

We have a 4 second timeout and if we get a 408, 409, 429, or 5xx response code in that period, 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. We strongly recommend only using test data with any third-party service you do not have a trusted relationship with.

More ideas & examples

If you're looking to see some real world examples, take a look at some of our recipes.

Was this article helpful?