Message status webhook examples

For the exhaustive schema-derived catalog, see all examples.

What it is

Handle message updates for WhatsApp, Messenger, Email, SMS, and Voice messages.

Before you begin

Create a public HTTPS endpoint in your application.
Configure a YCloud webhook endpoint for the event types you need.
Store the endpoint signing secret securely.
Make event processing idempotent.

How it works

YCloud sends an HTTP POST request when the event occurs. Verify the signature, durably record the event, return a 2xx response, and process slow work asynchronously.

Request

The scenarios below show requests delivered to your webhook URL. Treat the event id as the delivery identifier and use type to route the payload.

Response

Return a 2xx status after accepting the event.

HTTP/1.1 200 OK

For endpoint setup, signature validation, and retry behavior, see Configure webhooks.

For WhatsApp, after successfully requesting the API to send messages, messages have a status of accepted. Message status updates will trigger the whatsapp.message.updated webhook. Typically, the message status:

Changes to failed if we are unable to deliver this message.
Changes to sent if it’s possible to deliver this message, and later it may change to failed, delivered, or read.
Changes to delivered or read if this message was delivered to the recipient’s device.

But the actual situation is complex. First, we do not guarantee the order of webhook notifications, especially when the events occur almost simultaneously. Second, delivered events may happen after failed, and vice versa, especially when the end user is using multiple devices.

Message Sent

In this case, your webhook endpoint received a message sent event:

The message status is sent, which means the message is in transit within WhatsApp’s systems.
Contains information about the conversation, including the time when the conversation expires, and the origin type.
Contains the estimated pricingCategory and totalPrice we may charge you.
Contains wamid, which is the original message ID on WhatsApp’s platform, starting with wamid..

Request

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEVCy8eNqD9EvcFI",
  "type": "whatsapp.message.updated",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "recipientUserId" : "US.13491208655302741918",
    "parentRecipientUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Pablo M."
    },
    "status": "sent",
    "pricingCategory": "marketing",
    "totalPrice": 0.0,
    "currency": "USD",
    "createTime": "2022-03-01T12:00:00.000Z",
    "sendTime": "2022-03-01T12:00:01.000Z",
    "bizType": "whatsapp",
    "type": "text",
    "text": {
      "body": "Hi there! How can we help?"
    },
    "externalId": "EXTERNAL-ID"
  }
}'

Response

Acknowledge the delivery after durably accepting the event.

HTTP/1.1 200 OK

Explanation

totalPrice is only an estimated price before the first message is delivered, and it becomes the final price when the status is delivered or read. The balance taken up by those messages that are sent but haven’t been delivered will not be available until the messages are dropped (Sent messages that are not delivered for 30 days are dropped).
Generally, a sent message changes to delivered or read soon, except:
- The recipient’s WhatsApp account is offline, your sent WhatsApp messages won’t be delivered until the recipient has working or active internet services.
- Any message sent to a contact who has blocked you will always show the message sent, and will never change to delivered.
- The recipient has turned off read receipts, and you won’t receive the message read receipts.
- The message changes to failed later with error code 131026, which means “Message Undeliverable.”, or “Receiver is incapable of receiving this message”. This is most likely that the recipient is not registered, or is using an old WhatsApp version.
- The message was not delivered to create a high quality user experience. See Per-User Marketing Template Message Limits.

Message Delivered

In this case, your webhook endpoint received a message delivered event:

The message status is delivered, which means the message was delivered to the recipient’s device.

Request

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEVCy8eNqD9EvcFI",
  "type": "whatsapp.message.updated",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "recipientUserId" : "US.13491208655302741918",
    "parentRecipientUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Pablo M.",
      "username": "@pablomorales"
    },
    "status": "delivered",
    "pricingModel": "PMP",
    "pricingType": "regular",
    "pricingCategory": "marketing",
    "totalPrice": 0.0,
    "currency": "USD",
    "createTime": "2022-03-01T12:00:00.000Z",
    "sendTime": "2022-03-01T12:00:01.000Z",
    "deliverTime": "2022-03-01T12:00:02.000Z",
    "bizType": "whatsapp",
    "type": "text",
    "text": {
      "body": "Hi there! How can we help?"
    },
    "externalId": "EXTERNAL-ID"
  }
}'

Response

Acknowledge the delivery after durably accepting the event.

HTTP/1.1 200 OK

Explanation

This event indicates that the message sent by your business was delivered to the user’s device.
For a status to beread, it must have been delivered. In some scenarios, such as when a user is in the chat screen and a message arrives, the message is delivered and read almost simultaneously. In this or other similar scenarios, the delivered notification will not be sent back, as it is implied that a message has been delivered if it has been read. The reason for this behavior is internal optimization.
It’s possible for us to generate more than 1 delivered webhook event for the same message, especially if the end user is using multiple devices.
pricingModel: “PMP”— indicates per-message pricing applies. See also whatsapp-message-pricing-updates
pricingType
- regular — indicates the message is billable.
- free_customer_service — indicates the message is free because it was either a utility template message or non-template message sent within a customer service window.
- free_entry_point — indicates the message is free because it is part of a free-entry point conversation.

Message Read

In this case, your webhook endpoint received a message read event:

The message status is read, which means the message was read by the recipient.

Request

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEVCy8eNqD9EvcFI",
  "type": "whatsapp.message.updated",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "recipientUserId" : "US.13491208655302741918",
    "parentRecipientUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Pablo M.",
      "username": "@pablomorales"
    },
    "status": "read",
    "pricingModel": "PMP",
    "pricingType": "regular",
    "pricingCategory": "marketing",
    "totalPrice": 0.0,
    "currency": "USD",
    "createTime": "2022-03-01T12:00:00.000Z",
    "sendTime": "2022-03-01T12:00:01.000Z",
    "deliverTime": "2022-03-01T12:00:02.000Z",
    "readTime": "2022-03-01T12:00:02.000Z",
    "bizType": "whatsapp",
    "type": "text",
    "text": {
      "body": "Hi there! How can we help?"
    },
    "externalId": "EXTERNAL-ID"
  }
}'

Response

Acknowledge the delivery after durably accepting the event.

HTTP/1.1 200 OK

Explanation

If the recipient has turned off read receipts, you won’t receive the message read receipts.

Message Failed

In this case, your webhook endpoint received a message failed event:

The message status is failed.
Contains errroCode, errorMessage, and whatsappApiError.

Request

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEVCy8eNqD9EvcFI",
  "type": "whatsapp.message.updated",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "recipientUserId" : "US.13491208655302741918",
    "parentRecipientUserId": "US.ENT.11815799212886844830",
    "status": "failed",
    "errorCode": "100",
    "errorMessage": "Parameter Invalid",
    "whatsappApiError": {
      "message": "(#100) Invalid parameter",
      "type": "OAuthException",
      "code": "100",
      "fbtrace_id": "AwmiSOCojlAkqvjCTjGt37r",
      "error_data": {
        "messaging_product": "whatsapp",
        "details": "Parameter Invalid"
      }
    },
    "pricingCategory": "marketing",
    "totalPrice": 0.0,
    "currency": "USD",
    "bizType": "whatsapp",
    "type": "text",
    "text": {
      "body": "Hi there! How can we help?"
    },
    "externalId": "EXTERNAL-ID"
  }
}'

Response

Acknowledge the delivery after durably accepting the event.

HTTP/1.1 200 OK

Explanation

These events are intended to notify you of status changes for outbound messages you’ve previously sent to customers.
The reason for the messaging failure is typically the message request parameters are invalid, the customer’s phone number is not registered, etc. See also WhatsApp Errors for error handling.
whatsappApiError is provided if we tried to submit this message to Meta’s WhatsApp platform to help you understand the error details. See also Cloud API Error Codes.
We do not charge you for failed messages.

Email delivery update

Use email.delivery.updated when an email delivery status changes to delivered or failed.

Request

{
  "id": "evt_example_email_delivery_updated",
  "type": "email.delivery.updated",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "emailDelivery": {
    "emailId": "email_12345678",
    "recipientAddress": "customer@example.com",
    "status": "delivered",
    "externalId": "order_123"
  }
}

Response

Acknowledge the delivery after durably accepting the event.

HTTP/1.1 200 OK

Explanation

Correlate the delivery with emailId and recipientAddress: the status applies to this recipient. Use externalId when supplied to match your own record. Inspect errorCode and errorMessage on a failed delivery. The payload property is emailDelivery, not whatsappMessage.

SMS delivery update

Use sms.message.updated when an SMS delivery status changes to delivered or undelivered.

Request

{
  "id": "evt_example_sms_message_updated",
  "type": "sms.message.updated",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "sms": {
    "id": "sms_12345678",
    "to": "+16315551111",
    "status": "delivered",
    "externalId": "order_123"
  }
}

Response

Acknowledge the delivery after durably accepting the event.

HTTP/1.1 200 OK

Explanation

Identify the SMS with sms.id and read sms.status. Inspect errorCode when the delivery fails. SMS uses undelivered for a negative delivery receipt; do not apply the WhatsApp read status model to this event.

Voice delivery update

Use voice.message.updated when a Voice message status changes to delivered or undelivered.

Request

{
  "id": "evt_example_voice_message_updated",
  "type": "voice.message.updated",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "voice": {
    "id": "voice_12345678",
    "to": "+16315551111",
    "status": "delivered",
    "externalId": "verification_123"
  }
}

Response

Acknowledge the delivery after durably accepting the event.

HTTP/1.1 200 OK

Explanation

Identify the Voice message with voice.id and read voice.status. Inspect errorCode when supplied. This delivery event belongs to the Voice messaging API; it is separate from the WhatsApp Calling lifecycle events.

Messenger outbound read snapshot

Subscribe to messenger.message.updated for saved ordinary one-to-one outbound snapshots. A delivery retry retains Event.id; recreating an event from the same source fact can produce a new Event.id. Correlate updates by messengerMessage.id.

Submission and receipt states

accepted means Meta accepted the submission, not that the message was sent or delivered. rejected is a definitive submission rejection; unknown is an unconfirmed outcome and must not be treated as failure. Do not automatically resubmit a message after a timeout or an unknown result. Check its saved status using a returned message ID when available, or contact support. A snapshot preserves the current saved facts, with read taking precedence over delivered, sent, and the submission result. Late receipts do not downgrade that state. You may receive repeated snapshots or miss intermediate states. Use GET /v2/messenger/messages/{id} with from, or retrieve by the confirmed Meta message ID, to reconcile your current saved state. Submission-result notifications are best effort. Do not depend on receiving a webhook for every synchronous send result. Optional IDs, errorCode and receipt times are omitted when unavailable. A stored submission error may remain present after later receipt facts establish a stronger state.

Request

{
  "id": "evt_89abcdef0123456789abcdef",
  "type": "messenger.message.updated",
  "apiVersion": "v2",
  "createTime": "2026-10-20T02:00:03.000Z",
  "messengerMessage": {
    "id": "1308528868252065792",
    "metaMessageId": "m_EXAMPLE_OUT_001",
    "from": "422500000000000",
    "to": "100800000000000",
    "type": "text",
    "text": {
      "body": "How can I help you?"
    },
    "status": "read",
    "createTime": "2026-10-20T02:00:00.000Z",
    "updateTime": "2026-10-20T02:00:03.000Z",
    "readTime": "2026-10-20T02:00:03.000Z"
  }
}

Response

HTTP/1.1 200 OK

Explanation

The Facebook Page ID is from and the customer PSID is to. This example exposes the saved read state without inventing missing sendTime or deliverTime. id is the YCloud message ID, while metaMessageId is the provider identity.

Messenger message reaction

Request

{
  "id": "evt_abcdef0123456789abcdef01",
  "type": "messenger.message_reaction.updated",
  "apiVersion": "v2",
  "createTime": "2026-10-20T02:00:04.000Z",
  "messengerMessageReaction": {
    "pageId": "422500000000000",
    "psid": "100800000000000",
    "metaMessageId": "m_EXAMPLE_OUT_001",
    "action": "react",
    "reaction": "love",
    "emoji": "❤️"
  }
}

Response

HTTP/1.1 200 OK

Explanation

Use pageId and psid to identify the conversation, and metaMessageId to identify the target message. A reaction is an interaction and does not change the delivery status. The target may have no local YCloud message record. Preserve the source createTime; repeated deliveries may occur. Verify YCloud-Signature against the raw body before returning a successful response.

Messenger message reaction withdrawn

Request

{
  "id": "evt_bcdef0123456789abcdef012",
  "type": "messenger.message_reaction.updated",
  "apiVersion": "v2",
  "createTime": "2026-10-20T02:00:05.000Z",
  "messengerMessageReaction": {
    "pageId": "422500000000000",
    "psid": "100800000000000",
    "metaMessageId": "m_EXAMPLE_OUT_001",
    "action": "unreact"
  }
}

Response

HTTP/1.1 200 OK

Explanation

Remove the reaction associated with this Page, customer PSID, and target Meta message. unreact can omit reaction and emoji. Do not require a local message ID or infer a message status change. HTTP delivery retries keep the same event ID and body; repeated source callbacks may create a new event ID. Verify YCloud-Signature against the raw body before returning a successful response.

​What it is

​Before you begin

​How it works

​Request

​Response

​Message Sent

​Request

​Response

​Explanation

​Message Delivered

​Request

​Response

​Explanation

​Message Read

​Request

​Response

​Explanation

​Message Failed

​Request

​Response

​Explanation

​Email delivery update

​Request

​Response

​Explanation

​SMS delivery update

​Request

​Response

​Explanation

​Voice delivery update

​Request

​Response

​Explanation

​Messenger outbound read snapshot

​Submission and receipt states

​Request

​Response

​Explanation

​Messenger message reaction

​Request

​Response

​Explanation

​Messenger message reaction withdrawn

​Request

​Response

​Explanation

What it is

Before you begin

How it works

Request

Response

Message Sent

Request

Response

Explanation

Message Delivered

Request

Response

Explanation

Message Read

Request

Response

Explanation

Message Failed

Request

Response

Explanation

Email delivery update

Request

Response

Explanation

SMS delivery update

Request

Response

Explanation

Voice delivery update

Request

Response

Explanation

Messenger outbound read snapshot

Submission and receipt states

Request

Response

Explanation

Messenger message reaction

Request

Response

Explanation

Messenger message reaction withdrawn

Request

Response

Explanation