Reporting Webhooks

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

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

Set up webhooks

Log in and go to Data & Integrations > Integrations.
Find and select Reporting Webhooks.
Click Add Reporting Webhook.
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.
Select the events you want to receive.
(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.
Click Save and Enable Webhook.

Timeouts and failures

We have a 4 second timeout for calls to your webhook endpoint. If we don't get a successful (2xx) response during those 4 seconds, we retry the webhook over a period of seven days with an exponential backoff. We backlog subsequent webhook calls and won't continue processing them until the timed-out webhook call returns a successful response or the seven day retry period expires.

If your webhook server responds with any of the following status codes, we'll wait for one hour before we retry the failed call. As with timeouts, we use the same exponential backoff for retries and we'll backlog subsequent webhook calls until the failed call returns a successful response.

Error codes: 400, 401, 402, 403, 404, 405, 410, 429, 500, 502, 521.
Error responses: EOF, server misbehaving, connect: connection refused, read: connection reset by peer, tls: failed to verify certificate: x509:

If you have issues with your webhook server and you want 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.

Client Libraries

Shell Curl

Webhooks

Webhooks Webhooks

postReporting webhook format

Webhook

Reporting webhook format

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

Headers

x-cio-timestamp
Type: integerFormat: unix timestamp
required

The timestamp when the request was sent.
x-cio-signature
Type: string
required

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.

Body

application/json

Events that occur when a customer subscribes or unsubscribes from your messages.

A person subscribed to messages from you—their unsubscribed attribute was set to false.

metric
enum
const:
subscribed
required

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

values
subscribed
event_id
Type: string ·
required

The unique ID of the reporting webhook event being sent.

object_type
Type: stringenum
required

The channel that triggered the subscription change. If the subscription change wasn't triggered from a message, or we can't determine which message triggered the change, the object_type is customer.

values
customer
email
sms
push
in_app
slack
webhook
whatsapp
timestamp
Type: integer · Format: unix timestamp
required

The unix timestamp when the event occurred.

data
Type: object
required

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

postreportingWebhook

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