Webhook events & payloads

You can create webhook endpoints that subscribe to the events listed on this page. Each webhook event includes an example payload.

Each webhook event payload also contains properties unique to the event depending on its type. You can find the unique properties in the individual event type sections.

See also Test webhooks for the detailed structured payload object.

Webhook payload object common properties

Key	Type	Description
id	string	Unique identifier for the object.
type	string	Type of the event (e.g., `sms.message.updated`).
apiVersion	string	The API version used to render this event. This property is currently always `v2`.
createTime	string	The time at which this event is created, formatted in RFC 3339. e.g., `2022-06-01T12:00:00.000Z`.

email.delivery.updated

Occurs when an email delivery status is updated, and the status changes to delivered or failed.

Payload property emailDelivery is returned for this event type. For example:

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "email.delivery.updated",
  "apiVersion": "v2",
  "createTime": "2022-03-01T12:00:00.000Z",
  "emailDelivery": {
    "emailId": "em123456",
    "recipientAddress": "[email protected]",
    "status": "failed",
    "errorCode": "402",
    "errorMessage": "Unsubscribes",
    "externalId": "ext_1234567890"
  }
}

sms.message.updated

Occurs when an SMS message status is updated, and the status changes to delivered or undelivered.

Payload property sms is returned for this event type. For example:

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "sms.message.updated",
  "apiVersion": "v2",
  "createTime": "2022-03-01T12:00:00.000Z",
  "sms": {
    "id": "string",
    "to": "+447901614024",
    "status": "delivered",
    "text": "Your verification code is 123456.",
    "senderId": "YCloud",
    "regionCode": "GB",
    "totalSegments": 1,
    "totalPrice": 0.0085,
    "currency": "USD",
    "createTime": "2022-03-01T12:00:00.000Z",
    "updateTime": "2022-03-01T12:00:00.000Z"
  }
}

voice.message.updated

Occurs when a voice message status is updated, and the status changes to delivered or undelivered.

Payload property voice is returned for this event type. For example:

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "voice.message.updated",
  "apiVersion": "v2",
  "createTime": "2022-03-01T12:00:00.000Z",
  "voice":  {
    "id": "v123456",
    "to": "+447901614024",
    "status": "delivered",
    "verificationCode": "1234",
    "language": "en",
    "regionCode": "GB",
    "totalPrice": 0.0085,
    "currency": "USD",
    "errorCode": "Error code when the message is undeliverable.",
    "createTime": "2022-03-01T12:00:00.000Z",
    "updateTime": "2022-03-01T12:00:00.000Z",
    "externalId": "ext_123456"
  }
}