For each webhook event, you can review when the event occurs, an example payload, and descriptions about the payload object parameters.
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.
For more specific payload examples, see Webhook Payload Examples.
Webhook payload object common properties
Key | Type | Description |
---|---|---|
id | string | Unique identifier for the event. |
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 included 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.inbound.received
Occurs when an SMS inbound message is received, which means a user replies to your message. Please contact our customer service, and register your Sender IDs to enable this feature.
Payload property smsInbound
is included for this event type. For example:
{
"id": "evt_eBttMrYvJhzLpzzX",
"type": "sms.inbound.received",
"apiVersion": "v2",
"createTime": "2023-02-02T12:00:05.000Z",
"smsInbound": {
"id": "message-id",
"from": "+447901614024",
"to": "+1xxxxxx",
"text": "yes",
"sendTime": "2023-02-02T12:00:00.000Z"
}
}
sms.message.updated
Occurs when an SMS message status is updated, and the status changes to delivered
or undelivered
.
Payload property sms
is included 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 included 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"
}
}
whatsapp.business_account.reviewed
Occurs when a WhatsApp Business Account has been reviewed.
Payload property whatsappBusinessAccount
is included for this event type. For example:
{
"id": "evt_djeIQXaQPQyUcRFi",
"type": "whatsapp.business_account.reviewed",
"apiVersion": "v2",
"createTime": "2022-03-01T12:00:00.000Z",
"whatsappBusinessAccount": {
"id": "106681...",
"name": "whatsapp-business-account-name",
"accountReviewStatus": "APPROVED",
"decision": "APPROVED"
}
}
whatsapp.business_account.updated
Occurs when a policy violation happened, a WhatsApp Business Account has been banned and more.
Payload property whatsappBusinessAccount
is included for this event type. For example:
{
"id": "evt_djeIQXaQPQyUcRFi",
"type": "whatsapp.business_account.updated",
"apiVersion": "v2",
"createTime": "2022-03-01T12:00:00.000Z",
"whatsappBusinessAccount": {
"id": "106681...",
"name": "whatsapp-business-account-name",
"accountReviewStatus": "APPROVED",
"updateEvent": "ACCOUNT_RESTRICTION",
"restrictions": [
{
"restriction_type": "RESTRICTED_ADD_PHONE_NUMBER_ACTION",
"expiration": "2022-12-12T07:09:27.000Z"
}
],
"banState": "REINSTATE",
"banDate": "December 9, 2022",
"violationType": "SPAM"
}
}
whatsapp.inbound_message.received
Occurs when a WhatsApp inbound message is received.
Payload property whatsappInboundMessage
is included for this event type. For example:
{
"id": "evt_djeIQXaQPQyUcRFi",
"type": "whatsapp.inbound_message.received",
"apiVersion": "v2",
"createTime": "2022-03-01T12:00:00.000Z",
"whatsappInboundMessage": {
"id": "wim123456",
"wabaId": "whatsapp-business-account-id",
"from": "+447901614024",
"customerProfile": {
"name": "John"
},
"to": "+447901614024",
"sendTime": "2022-03-01T12:00:00.000Z",
"type": "text",
"text": {
"body": "Hi there!"
}
}
}
whatsapp.message.updated
Occurs when a WhatsApp outbound message status is updated, and the status changes to failed
, sent
, delivered
, or read
.
Payload property whatsappMessage
is included for this event type. For example:
{
"id": "evt_djeIQXaQPQyUcRFi",
"type": "whatsapp.message.updated",
"apiVersion": "v2",
"createTime": "2022-03-01T12:00:00.000Z",
"whatsappMessage": {
"id": "wm123456",
"wabaId": "whatsapp-business-account-id",
"from": "+447901614024",
"to": "+447901614024",
"status": "delivered",
"type": "text",
"text": {
"body": "Your verification code is 123456."
},
"conversation": {
"id": "8078ed05301c40a08d3d1845c94ca18b",
"originType": "business_initiated",
"expireTime": "2022-03-02T12:00:00.000Z"
},
"createTime": "2022-03-01T12:00:00.000Z",
"updateTime": "2022-03-01T12:00:00.000Z",
"externalId": "ext_123456"
}
}
whatsapp.phone_number.name_updated
Occurs when a WhatsApp business account phone number's name has been approved or rejected. See also phone_number_name_update.
Payload property whatsappPhoneNumber
is included for this event type. For example:
{
"id": "evt_djeIQXaQPQyUcRFi",
"type": "whatsapp.phone_number.name_updated",
"apiVersion": "v2",
"createTime": "2022-03-01T12:00:00.000Z",
"whatsappPhoneNumber": {
"phoneNumber": "+16315551111",
"displayPhoneNumber": "+1 631-555-1111",
"wabaId": "whatsapp-business-account-id",
"decision": "APPROVED",
"requestedVerifiedName": "requested-verified-name",
"rejectionReason": ""
}
}
whatsapp.phone_number.quality_updated
Occurs when a WhatsApp business account phone number's quality-related status is updated. See also phone_number_quality_update.
Payload property whatsappPhoneNumber
is included for this event type. For example:
{
"id": "evt_djeIQXaQPQyUcRFi",
"type": "whatsapp.phone_number.quality_updated",
"apiVersion": "v2",
"createTime": "2022-03-01T12:00:00.000Z",
"whatsappPhoneNumber": {
"phoneNumber": "+16315551111",
"displayPhoneNumber": "+1 631-555-1111",
"wabaId": "whatsapp-business-account-id",
"qualityRating": "GREEN",
"messagingLimit": "TIER_50"
}
}
whatsapp.template.category_updated
Occurs when a WhatsApp template category
is updated. The old category will be set to previousCategory
.
Meta will begin the first template category migration on March 27, 2023 (2023-03-27T00:00:00 PDT, UTC-07:00) and expect to complete on April 1, 2023.
Payload property whatsappTemplate
is included for this event type. For example:
{
"id": "evt_djeIQXaQPQyUcRFi",
"type": "whatsapp.template.category_updated",
"apiVersion": "v2",
"createTime": "2022-03-01T12:00:00.000Z",
"whatsappTemplate": {
"wabaId": "whatsapp-business-account-id",
"name": "sample_template",
"language": "en",
"category": "UTILITY",
"previousCategory": "TRANSACTIONAL"
}
}
whatsapp.template.reviewed
Occurs when a WhatsApp template statusUpdateEvent
changed, such as REJECTED
, APPROVED
, and the status may change to REJECTED
, APPROVED
, PAUSED
, DISABLED
, or IN_APPEAL
.
Payload property whatsappTemplate
is included for this event type. For example:
{
"id": "evt_djeIQXaQPQyUcRFi",
"type": "whatsapp.template.reviewed",
"apiVersion": "v2",
"createTime": "2022-03-01T12:00:00.000Z",
"whatsappTemplate": {
"wabaId": "whatsapp-business-account-id",
"name": "sample_template",
"language": "en",
"category": "OTP",
"status": "REJECTED",
"reason": "The message template is a duplicate of an existing template.",
"createTime": "2022-03-01T12:00:00.000Z",
"updateTime": "2022-03-01T12:00:00.000Z",
"statusUpdateEvent": "PENDING_DELETION"
}
}