Customer.io Webhooks

Customer.io lets you subscribe to reporting webhooks. This page details the events that we report back to your webhook URL.

Reporting webhooks

Set up webhooks to inform an external service about Customer.io events. Webhooks can notify you immediately when immediately when customer attributes change or when people open your messages.

Set up webhooks

  1. Log in and go to Settings > Integrations.

  2. Find and select Reporting Webhooks.

  3. Click Add Reporting Webhook.

  4. Enter the Webhook Endpoint—the URL where you want to receive events. The URL can be either HTTP or HTTPs, but we recommended HTTPS to protect customer information.

  5. Select the events you want to receive.

  6. (Optional) Select the Send Frequency and Body Content options.

    • Send Frequency: This determines whether you receive events the first time they happen or every time they happen.
    • Body Content: Enable this to include message body content in all of the "Sent" events we send to you.
  7. Click Save and Enable Webhook.

Timeouts and Failures

Webhooks have 4 second timeout. If Customer.io does not receive a successful (2xx) response during those 4 seconds, Customer.io will retry the webhook over a 7-day period with an exponential backoff. We will not move past a failing webhook until we get a successful (2xx) response or until 7 days have expired. Subsequent webhooks will be backlogged and will get processed after the success or failure of the webhook that failed and triggered the backlog.

If you wish to temporarily block our servers, you can look up the current set of IP addresses we use via this API endpoint.

Securely Verifying Requests

For security purposes, every email webhook is delivered with an X-CIO-Signature header. This signature is generated by combining your webhook signing key with the body of webhook request using a standard HMAC-SHA256 hash. You can find the signing key on the Email Activity Webhook integration page in your account settings. (This is the same page where you enter your webhook endpoint.)

To validate a signed request, first you'll need to retrieve the X-CIO-Timestamp header sent with the webhook request, and the body of the request. Combine the version number, timestamp and body delimited by colons to form a string in the form v0:<timestamp>:<body> (the version number is always v0). Using HMAC-SHA256, hash the string using your webhook signing secret as the hash key. Compare this value to the value of the X-CIO-Signature header sent with the request to confirm that the request originated with Customer.io.

Reporting webhook format Webhook

Customer.io sends events to your webhook URL in the following format. Events are generally organized by object_type—representing the message or Customer.io action (i.e. email, sms, etc)—and the specific metric pertaining to the type (i.e. sent, bounced, etc).

header Parameters
x-cio-timestamp
required
integer <unix timestamp>

The timestamp when the request was sent.

x-cio-signature
required
string

A string combining your webhook signing key with the body of webhook request using an HMAC-SHA256 hash, used to help you securely verify requests.

Request Body: application/json
One of
event_id
required
string

The unique identifier for the event.

object_type
required
string
Value: "customer"

The event represents a customer subscribing or unsubscribing.

metric
required
string
Enum: "subscribed" "unsubscribed"

The metric recorded by the event. For customer events, this is whether the customer explicitly subscribed or unsubscribed.

timestamp
required
integer <unix timestamp>

The unix timestamp when the event occurred.

required
object

Contains information about the event, specific to the object_type and metric.

Request samples

Content type
application/json
Example
{
  • "event_id": "01E4C4CT6YDC7Y5M7FE1GWWPQJ",
  • "object_type": "customer",
  • "metric": "subscribed",
  • "timestamp": 1613063089,
  • "data": {
    • "customer_id": "42",
    • "email_address": "test@example.com",
    • "identifiers": {
      }
    }
}

Customer Events

Customer events occur when a person's "unsubscribed" attribute is explicitly changed. This is a change that happens without a reference to a message. For example, if a customer changes a subscription preference in their account information, of their own volition. subscribed metrics represent a change to false; unsubscribed metrics represent a change to true.

event_id
required
string

The unique identifier for the event.

object_type
required
string
Value: "customer"

The event represents a customer subscribing or unsubscribing.

metric
required
string
Enum: "subscribed" "unsubscribed"

The metric recorded by the event. For customer events, this is whether the customer explicitly subscribed or unsubscribed.

timestamp
required
integer <unix timestamp>

The unix timestamp when the event occurred.

required
object

Contains information about the event, specific to the object_type and metric.

{
  • "event_id": "01E4C4CT6YDC7Y5M7FE1GWWPQJ",
  • "object_type": "customer",
  • "metric": "subscribed",
  • "timestamp": 1613063089,
  • "data": {
    • "customer_id": "42",
    • "email_address": "test@example.com",
    • "identifiers": {
      }
    }
}

Email Events

Events that occur during the lifecycle of an email delivery. Some events are reported by the delivery provider.

Email Drafted

An email draft was created.

event_id
required
string

The unique identifier for the event.

object_type
required
string
Value: "email"

The event relates to an email action.

timestamp
required
integer <unix timestamp>

The unix timestamp when the event occurred.

metric
required
string
Value: "drafted"

The metric recorded by the event. For customer events, this is whether the customer explicitly subscribed or unsubscribed.

required
object

Contains information about the event, specific to the object_type and metric.

{
  • "event_id": "01E4C4CT6YDC7Y5M7FE1GWWPQJ",
  • "object_type": "email",
  • "timestamp": 1613063089,
  • "metric": "drafted",
  • "data": {
    • "customer_id": "42",
    • "delivery_id": "ZAIAAVTJVG0QcCok0-0ZKj6yiQ==",
    • "action_id": 96,
    • "broadcast_id": 2,
    • "journey_id": 5,
    • "parent_action_id": 1,
    • "identifiers": {
      },
    • "content": "string",
    • "subject": "string",
    • "recipient": "test@example.com"
    }
}

Email attempted

An email could not be sent to the email provider. This metric indicates that we will retry to send the email.

event_id
required
string

The unique identifier for the event.

object_type
required
string
Value: "email"

The event relates to an email action.

timestamp
required
integer <unix timestamp>

The unix timestamp when the event occurred.

metric
required
string
Value: "attempted"

An email could not be sent to the delivery provider and will be retried. The failure_message provides the reason for the failure.

required
object

Contains information about the event, specific to the object_type and metric.

{
  • "event_id": "01E4C4CT6YDC7Y5M7FE1GWWPQJ",
  • "object_type": "email",
  • "timestamp": 1613063089,
  • "metric": "attempted",