Customer.io Reporting Webhooks

{
  "webhooks": {
    "reportingWebhook": {
      "post": {
        "summary": "Reporting webhook format",
        "description": "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).",
        "operationId": "reportingWebhook",
        "security": [],
        "parameters": [
          {
            "name": "x-cio-timestamp",
            "schema": {
              "type": "integer",
              "format": "unix timestamp"
            },
            "description": "The timestamp when the request was sent.",
            "in": "header",
            "required": true
          },
          {
            "name": "x-cio-signature",
            "in": "header",
            "description": "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](/webhooks#securely-verifying-requests). \n",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {},
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/customer_event"
                  },
                  {
                    "$ref": "#/components/schemas/email_event"
                  },
                  {
                    "$ref": "#/components/schemas/push_event"
                  },
                  {
                    "$ref": "#/components/schemas/in_app_event"
                  },
                  {
                    "$ref": "#/components/schemas/sms_event"
                  },
                  {
                    "$ref": "#/components/schemas/slack_event"
                  },
                  {
                    "$ref": "#/components/schemas/webhook_event"
                  },
                  {
                    "$ref": "#/components/schemas/whatsapp_event"
                  }
                ]
              },
              "examples": {
                "customer_subscribed": {
                  "summary": "Customer subscribed event",
                  "value": {
                    "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"
                      }
                    }
                  }
                },
                "email_sent": {
                  "summary": "Email sent event",
                  "value": {
                    "metric": "sent",
                    "event_id": "01E4C4CT6YDC7Y5M7FE1GWWPQJ",
                    "object_type": "email",
                    "timestamp": 1613063089,
                    "data": {
                      "action_id": 42,
                      "broadcast_id": 9,
                      "customer_id": "0200000001",
                      "delivery_id": "RPILAgUBcRhIBqSfeiIwdIYJKxTY",
                      "identifiers": {
                        "id": "42",
                        "email": "test@example.com",
                        "cio_id": "d9c106000001"
                      },
                      "recipient": "test@example.com"
                    }
                  }
                },
                "sms_sent": {
                  "summary": "SMS sent event",
                  "value": {
                    "metric": "sent",
                    "event_id": "01E4C4CT6YDC7Y5M7FE1GWWPQJ",
                    "object_type": "sms",
                    "timestamp": 1613063089,
                    "data": {
                      "action_id": 42,
                      "broadcast_id": 9,
                      "customer_id": "0200000001",
                      "delivery_id": "RPILAgUBcRhIBqSfeiIwdIYJKxTY",
                      "identifiers": {
                        "id": "42",
                        "email": "test@example.com",
                        "cio_id": "d9c106000001"
                      },
                      "recipient": "+15551234567"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "customer_event": {
        "x-scalar-ignore": true,
        "title": "Customer",
        "description": "Events that occur when a customer subscribes or unsubscribes from your messages.",
        "oneOf": [
          {
            "$ref": "#/components/schemas/person_subscribed"
          },
          {
            "$ref": "#/components/schemas/person_unsubscribed"
          },
          {
            "$ref": "#/components/schemas/person_cio_subscription_preferences_changed"
          }
        ]
      },
      "customer_event_common": {
        "x-scalar-ignore": true,
        "type": "object",
        "required": [
          "event_id",
          "object_type",
          "timestamp",
          "data"
        ],
        "properties": {
          "event_id": {
            "$ref": "#/components/schemas/event_id"
          },
          "object_type": {
            "type": "string",
            "enum": [
              "customer",
              "email",
              "sms",
              "push",
              "in_app",
              "slack",
              "webhook",
              "whatsapp"
            ],
            "description": "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`.",
            "example": "customer"
          },
          "timestamp": {
            "$ref": "#/components/schemas/webhook_timestamp"
          },
          "data": {
            "description": "Contains information about the event, specific to the `object_type` and `metric`.",
            "type": "object",
            "required": [
              "identifiers",
              "customer_id",
              "email_address"
            ],
            "properties": {
              "customer_id": {
                "$ref": "#/components/schemas/webhook_customer_id"
              },
              "email_address": {
                "$ref": "#/components/schemas/email_address"
              },
              "identifiers": {
                "$ref": "#/components/schemas/webhook_identifiers"
              }
            }
          }
        }
      },
      "person_subscribed": {
        "title": "Customer subscribed",
        "description": "A person subscribed to messages from you—their `unsubscribed` attribute was set to `false`.",
        "allOf": [
          {
            "type": "object",
            "required": [
              "metric"
            ],
            "properties": {
              "metric": {
                "type": "string",
                "enum": [
                  "subscribed"
                ],
                "description": "The metric recorded by the event. For `customer` events, this is whether the customer explicitly subscribed or unsubscribed."
              }
            }
          },
          {
            "$ref": "#/components/schemas/customer_event_common"
          }
        ]
      },
      "person_unsubscribed": {
        "title": "Customer unsubscribed",
        "description": "A person unsubscribed to messages from you—their `unsubscribed` attribute was set to `true`.",
        "allOf": [
          {
            "type": "object",
            "required": [
              "metric"
            ],
            "properties": {
              "metric": {
                "type": "string",
                "enum": [
                  "unsubscribed"
                ],
                "description": "The metric recorded by the event. For `customer` events, this is whether the customer explicitly subscribed or unsubscribed."
              }
            }
          },
          {
            "$ref": "#/components/schemas/customer_event_common"
          }
        ]
      },
      "person_cio_subscription_preferences_common": {
        "x-scalar-ignore": true,
        "oneOf": [
          {
            "title": "API triggered broadcast",
            "required": [
              "trigger_id",
              "broadcast_id",
              "delivery_id",
              "action_id"
            ],
            "type": "object",
            "properties": {
              "trigger_id": {
                "$ref": "#/components/schemas/trigger_id"
              },
              "customer_id": {
                "$ref": "#/components/schemas/webhook_customer_id"
              },
              "delivery_id": {
                "$ref": "#/components/schemas/delivery_id"
              },
              "action_id": {
                "$ref": "#/components/schemas/action_id_webhook"
              },
              "broadcast_id": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/broadcast_id"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "journey_id": {
                "$ref": "#/components/schemas/journey_id"
              },
              "parent_action_id": {
                "$ref": "#/components/schemas/parent_action_id"
              }
            }
          },
          {
            "title": "Campaign",
            "type": "object",
            "required": [
              "campaign_id",
              "delivery_id",
              "action_id"
            ],
            "properties": {
              "campaign_id": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/campaign_id"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "customer_id": {
                "$ref": "#/components/schemas/webhook_customer_id"
              },
              "delivery_id": {
                "$ref": "#/components/schemas/delivery_id"
              },
              "action_id": {
                "$ref": "#/components/schemas/action_id_webhook"
              },
              "journey_id": {
                "$ref": "#/components/schemas/journey_id"
              },
              "parent_action_id": {
                "$ref": "#/components/schemas/parent_action_id"
              },
              "trigger_event_id": {
                "$ref": "#/components/schemas/trigger_event_id"
              }
            }
          },
          {
            "title": "Newsletter",
            "type": "object",
            "required": [
              "newsletter_id",
              "delivery_id"
            ],
            "properties": {
              "customer_id": {
                "$ref": "#/components/schemas/webhook_customer_id"
              },
              "delivery_id": {
                "$ref": "#/components/schemas/delivery_id"
              },
              "newsletter_id": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/newsletter_id"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "content_id": {
                "$ref": "#/components/schemas/content_id_event"
              }
            }
          }
        ]
      },
      "person_cio_subscription_preferences_changed": {
        "title": "Customer changed subscription preferences",
        "description": "A person changed their subscription preferences through our subscription center or you changed their `cio_subscription_preferences` attribute values.\n\nSome fields in the `data` object change based on whether the message that resulted in the change originated from a broadcast, campaign, or newsletter.\n",
        "type": "object",
        "required": [
          "metric",
          "event_id",
          "data",
          "timestamp"
        ],
        "properties": {
          "metric": {
            "type": "string",
            "enum": [
              "cio_subscription_preferences_changed"
            ],
            "description": "The event we're reporting to your webhook endpoint. In this case, a person changed their subscription preferences."
          },
          "event_id": {
            "$ref": "#/components/schemas/event_id"
          },
          "object_type_type": {
            "type": "string",
            "enum": [
              "customer",
              "email",
              "sms",
              "push",
              "in_app",
              "slack",
              "webhook",
              "whatsapp"
            ],
            "description": "The channel that triggered the change to the person's subscription preferences. 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`. Most subscription changes are triggered by `email` or are `customer` initiated.",
            "example": "email"
          },
          "timestamp": {
            "$ref": "#/components/schemas/webhook_timestamp"
          },
          "data": {
            "allOf": [
              {
                "type": "object",
                "description": "Contains information about the event, specific to the `object_type` and `metric`.",
                "required": [
                  "identifiers",
                  "customer_id",
                  "email_address"
                ],
                "properties": {
                  "content": {
                    "type": "string",
                    "description": "If you enable the *Include body content and headers in all Sent events* when you set up your reporting webhook, you'll see this field. It contains the subscription preferences that a person changed in a stringified object format. The `topic_1` key refers to a topic with an ID of `1`; you can get more information about each topic from our [App API](/api/app/#operation/getTopics).",
                    "example": "{\"topics\":{\"topic_1\":true}}"
                  },
                  "customer_id": {
                    "$ref": "#/components/schemas/webhook_customer_id"
                  },
                  "email_address": {
                    "$ref": "#/components/schemas/email_address"
                  },
                  "identifiers": {
                    "$ref": "#/components/schemas/webhook_identifiers"
                  }
                }
              },
              {
                "$ref": "#/components/schemas/person_cio_subscription_preferences_common"
              }
            ]
          }
        }
      },
      "email_event": {
        "x-scalar-ignore": true,
        "title": "Email",
        "description": "Events representing an email.",
        "oneOf": [
          {
            "$ref": "#/components/schemas/email_drafted"
          },
          {
            "$ref": "#/components/schemas/email_attempted"
          },
          {
            "$ref": "#/components/schemas/email_sent"
          },
          {
            "$ref": "#/components/schemas/email_delivered"
          },
          {
            "$ref": "#/components/schemas/email_opened"
          },
          {
            "$ref": "#/components/schemas/email_clicked"
          },
          {
            "$ref": "#/components/schemas/email_converted"
          },
          {
            "$ref": "#/components/schemas/email_unsubscribed"
          },
          {
            "$ref": "#/components/schemas/email_bounced"
          },
          {
            "$ref": "#/components/schemas/email_dropped"
          },
          {
            "$ref": "#/components/schemas/email_spammed"
          },
          {
            "$ref": "#/components/schemas/email_failed"
          },
          {
            "$ref": "#/components/schemas/email_undeliverable"
          }
        ],
        "discriminator": {
          "propertyName": "metric"
        }
      },
      "email_event_common": {
        "x-scalar-ignore": true,
        "type": "object",
        "required": [
          "event_id",
          "object_type",
          "timestamp"
        ],
        "example": {
          "event_id": "01HXYZ1234567890ABCDEF",
          "object_type": "email",
          "timestamp": 1713484800
        },
        "properties": {
          "event_id": {
            "$ref": "#/components/schemas/event_id"
          },
          "object_type": {
            "type": "string",
            "enum": [
              "email"
            ],
            "description": "The event relates to an email action."
          },
          "timestamp": {
            "$ref": "#/components/schemas/webhook_timestamp"
          }
        }
      },
      "email_drafted": {
        "title": "Email drafted",
        "allOf": [
          {
            "$ref": "#/components/schemas/email_event_common"
          },
          {
            "type": "object",
            "required": [
              "metric",
              "data"
            ],
            "properties": {
              "metric": {
                "type": "string",
                "enum": [
                  "drafted"
                ],
                "description": "The metric recorded by the event. For `customer` events, this is whether the customer explicitly subscribed or unsubscribed."
              },
              "data": {
                "description": "Contains information about the event, specific to the `object_type` and `metric`.",
                "allOf": [
                  {
                    "$ref": "#/components/schemas/event_common_data"
                  },
                  {
                    "type": "object",
                    "required": [
                      "recipient",
                      "subject"
                    ],
                    "properties": {
                      "subject": {
                        "type": "string",
                        "description": "The subject of the email."
                      },
                      "recipient": {
                        "$ref": "#/components/schemas/recipient_not_templated"
                      }
                    }
                  }
                ]
              }
            }
          }
        ]
      },
      "email_attempted": {
        "title": "Email attempted",
        "allOf": [
          {
            "$ref": "#/components/schemas/email_event_common"
          },
          {
            "type": "object",
            "required": [
              "metric",
              "data"
            ],
            "properties": {
              "metric": {
                "type": "string",
                "enum": [
                  "attempted"
                ],
                "description": "An email could not be sent to the delivery provider and will be retried. The `failure_message` provides the reason for the failure."
              },
              "data": {
                "description": "Contains information about the event, specific to the `object_type` and `metric`.",
                "allOf": [
                  {
                    "$ref": "#/components/schemas/event_common_data"
                  },
                  {
                    "type": "object",
                    "required": [
                      "failure_message"
                    ],
                    "properties": {
                      "failure_message": {
                        "$ref": "#/components/schemas/failure_message"
                      }
                    }
                  }
                ]
              }
            }
          }
        ]
      },
      "email_sent": {
        "title": "Email sent",
        "allOf": [
          {
            "$ref": "#/components/schemas/email_event_common"
          },
          {
            "type": "object",
            "required": [
              "metric",
              "data"
            ],
            "properties": {
              "metric": {
                "type": "string",
                "enum": [
                  "sent"
                ],
                "description": "A message was successfully sent. If you enabled the *Include body content and headers in all Sent events* option, the payload includes the `content` of your message and, for emails with custom headers, a `data.headers` object alongside `content`."
              },
              "data": {
                "description": "Contains information about the event, specific to the `object_type` and `metric`.",
                "allOf": [
                  {
                    "$ref": "#/components/schemas/event_common_data"
                  },
                  {
                    "type": "object",
                    "required": [
                      "recipient",
                      "subject"
                    ],
                    "properties": {
                      "content": {
                        "type": "string",
                        "description": "The body content of your email. This key only appears if you enabled the *Include body content and headers in all Sent events* (*Body Content*) option when setting up your webhook."
                      },
                      "headers": {
                        "type": "object",
                        "description": "The headers sent with your email, as a map of header name to an array of values. This key only appears if you enabled the *Include body content and headers in all Sent events* (*Body Content*) option when setting up your webhook and the message included custom headers. This is a sibling of `content`—it is not nested inside it.",
                        "additionalProperties": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "example": {
                          "Customheader1": [
                            "customvalue1"
                          ]
                        }
                      },
                      "subject": {
                        "type": "string",
                        "description": "The subject of the email."
                      },
                      "recipient": {
                        "$ref": "#/components/schemas/recipient_not_templated"
                      }
                    }
                  }
                ]
              }
            }
          }
        ]
      },
      "email_delivered": {
        "title": "Email delivered",
        "allOf": [
          {
            "$ref": "#/components/schemas/email_event_common"
          },
          {
            "type": "object",
            "required": [
              "metric",
              "data"
            ],
            "properties": {
              "metric": {
                "type": "string",
                "enum": [
                  "delivered"
                ],
                "description": "A message was successfully delivered to a recipient."
              },
              "data": {
                "description": "Contains information about the event, specific to the `object_type` and `metric`.",
                "allOf": [
                  {
                    "$ref": "#/components/schemas/event_common_data"
                  },
                  {
                    "type": "object",
                    "required": [
                      "recipient",
                      "subject"
                    ],
                    "properties": {
                      "subject": {
                        "type": "string",
                        "description": "The subject of the email."
                      },
                      "recipient": {
                        "$ref": "#/components/schemas/recipient_not_templated"
                      }
                    }
                  }
                ]
              }
            }
          }
        ]
      },
      "email_opened": {
        "title": "Email opened",
        "allOf": [
          {
            "$ref": "#/components/schemas/email_event_common"
          },
          {
            "type": "object",
            "required": [
              "metric",
              "data"
            ],
            "properties": {
              "metric": {
                "type": "string",
                "enum": [
                  "opened"
                ],
                "description": "An email was opened."
              },
              "data": {
                "description": "Contains information about the event, specific to the `object_type` and `metric`.",
                "allOf": [
                  {
                    "$ref": "#/components/schemas/event_common_data"
                  },
                  {
                    "type": "object",
                    "required": [
                      "recipient"
                    ],
                    "properties": {
                      "subject": {
                        "type": "string",
                        "description": "The subject of the email."
                      },
                      "recipient": {
                        "$ref": "#/components/schemas/recipient_not_templated"
                      },
                      "proxied": {
                        "type": "boolean",
                        "description": "If true, the email was fetched by a proxy to hide the user identity, IP address, etc."
                      },
                      "prefetched": {
                        "type": "boolean",
                        "description": "If true, the email was opened by Gmail, Apple Privacy Protection, or a user agent identified as a machine."
                      },
                      "synthetic": {
                        "type": "boolean",
                        "description": "If true, Customer.io inferred the open event because we tracked a click event before we registered an open event (and a link in an email can't be clicked without the email being opened). This does not necessarily mean that the open was machine-oriented. The click—and therefore, the open—could have originated from either a machine or a person."
                      }
                    }
                  }
                ]
              }
            }
          }
        ]
      },
      "email_clicked": {
        "title": "Email clicked",
        "allOf": [
          {
            "$ref": "#/components/schemas/email_event_common"
          },
          {
            "type": "object",
            "required": [
              "metric",
              "data"
            ],
            "properties": {
              "metric": {
                "type": "string",
                "enum": [
                  "clicked"
                ],
                "description": "A tracked link in an email was clicked."
              },
              "data": {
                "description": "Contains information about the event, specific to the `object_type` and `metric`.",
                "allOf": [
                  {
                    "$ref": "#/components/schemas/event_common_data"
                  },
                  {
                    "type": "object",
                    "required": [
                      "recipient",
                      "subject",
                      "href",
                      "link_id"
                    ],
                    "properties": {
                      "subject": {
                        "type": "string",
                        "description": "The subject of the email."
                      },
                      "recipient": {
                        "$ref": "#/components/schemas/recipient_not_templated"
                      },
                      "href": {
                        "$ref": "#/components/schemas/href"
                      },
                      "link_id": {
                        "$ref": "#/components/schemas/link_id"
                      },
                      "machine": {
                        "type": "boolean",
                        "description": "If true, the click was generated by a machine."
                      }
                    }
                  }
                ]
              }
            }
          }
        ]
      },
      "email_converted": {
        "title": "Email converted",
        "allOf": [
          {
            "$ref": "#/components/schemas/email_event_common"
          },
          {
            "type": "object",
            "required": [
              "metric",
              "data"
            ],
            "properties": {
              "metric": {
                "type": "string",
                "enum": [
                  "converted"
                ],
                "description": "A person matched conversion criteria attributed to an email."
              },
              "data": {
                "description": "Contains information about the event, specific to the `object_type` and `metric`.",
                "allOf": [
                  {
                    "$ref": "#/components/schemas/event_common_data"
                  },
                  {
                    "type": "object",
                    "required": [
                      "recipient",
                      "subject"
                    ],
                    "properties": {
                      "subject": {
                        "type": "string",
                        "description": "The subject of the email."
                      },
                      "recipient": {
                        "$ref": "#/components/schemas/recipient_not_templated"
                      }
                    }
                  }
                ]
              }
            }
          }
        ]
      },
      "email_unsubscribed": {
        "title": "Email unsubscribed",
        "allOf": [
          {
            "$ref": "#/components/schemas/email_event_common"
          },
          {
            "type": "object",
            "required": [
              "metric",
              "data"
            ],
            "properties": {
              "metric": {
                "type": "string",
                "enum": [
                  "unsubscribed"
                ],
                "description": "The recipient unsubscribed based on a particular message."
              },
              "data": {
                "description": "Contains information about the event, specific to the `object_type` and `metric`.",
                "allOf": [
                  {
                    "$ref": "#/components/schemas/event_common_data"
                  },
                  {
                    "type": "object",
                    "required": [
                      "recipient",
                      "subject"
                    ],
                    "properties": {
                      "subject": {
                        "type": "string",
                        "description": "The subject of the email."
                      },
                      "recipient": {
                        "$ref": "#/components/schemas/recipient_not_templated"
                      }
                    }
                  }
                ]
              }
            }
          }
        ]
      },
      "email_bounced": {
        "title": "Email bounced",
        "allOf": [
          {
            "$ref": "#/components/schemas/email_event_common"
          },
          {
            "type": "object",
            "required": [
              "metric",
              "data"
            ],
            "properties": {
              "metric": {
                "type": "string",
                "enum": [
                  "bounced"
                ],
                "description": "The delivery provider could not deliver an email."
              },
              "data": {
                "description": "Contains information about the event, specific to the `object_type` and `metric`.",
                "allOf": [
             

# --- truncated at 32 KB (160 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/customer-io/refs/heads/main/openapi/_original/customer-io-reporting-webhooks-openapi.json