WhatsApp Business App Sent Message Sync Webhook Examples

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

What it is

Handle WhatsApp Business App sent-message synchronization events.

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.

Outbound Text message

In this case, your webhook endpoint received an outbound text message sent by a business customer to a WhatsApp user with the WhatsApp Business app or a supported companion device: Read the sent text from whatsappMessage.text.body.

Request

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_example_smb_echoes",
  "type": "whatsapp.smb.message.echoes",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+16315551111",
    "to": "+16315552222",
    "type": "text",
    "text": {
      "body": "Your order is ready for pickup."
    },
    "status": "sent",
    "createTime": "2026-10-08T12:00:00.000Z",
    "sendTime": "2026-10-08T12:00:00.000Z",
    "toUserId": "US.13491208655302741918",
    "toParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "username": "example_customer"
    }
  }
}'

Response

Acknowledge the delivery after durably accepting the event.

HTTP/1.1 200 OK

Explanation

Route the event by type, deduplicate it by id, and move slow or failure-prone work to an asynchronous processor.

Outbound Image message

In this case, your webhook endpoint received an outbound image message sent by a business customer to a WhatsApp user with the WhatsApp Business app or supported companion device.:

Contains image sent before.

Request

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEVCy8eNqD9EvcFI",
  "type": "whatsapp.smb.message.echoes",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "status": "sent",
    "from": "BUSINESS-PHONE-NUMBER",
    "to": "CUSTOMER-PHONE-NUMBER",
    "toUserId": "US.13491208655302741918",
    "toParentUserId": "US.1181579921288684483",
    "customerProfile": {
      "username": "@joee"
    },
    "wabaId": "WABA-ID",
    "createTime": "2022-03-01T12:00:00.000Z",
    "sendTime": "2022-03-01T12:00:01.000Z",
    "bizType": "whatsapp",
    "type": "image",
    "image": {
      "link": "https://api.ycloud.com/v2/whatsapp/media/download/5926236...",
      "id": "592623615738103",
      "sha256": "LeRpQJq/h4HTjm...",
      "mime_type": "image/jpeg"
    }
  }
}'

Response

Acknowledge the delivery after durably accepting the event.

HTTP/1.1 200 OK

Explanation

The image.link can be directly accessed in a few minutes for the convenience of the consumer, but you should always include an X-API-Key header to download this file within 30 days.

Outbound Video message

In this case, your webhook endpoint received an outbound video message sent by a business customer to a WhatsApp user with the WhatsApp Business app or supported companion device.:

Contains video sent before.

Request

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEVCy8eNqD9EvcFI",
  "type": "whatsapp.smb.message.echoes",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "status": "sent",
    "from": "BUSINESS-PHONE-NUMBER",
    "to": "CUSTOMER-PHONE-NUMBER",
    "toUserId": "US.13491208655302741918",
    "toParentUserId": "US.1181579921288684483",
    "customerProfile": {
      "username": "@joee"
    },
    "wabaId": "WABA-ID",
    "createTime": "2022-03-01T12:00:00.000Z",
    "sendTime": "2022-03-01T12:00:01.000Z",
    "bizType": "whatsapp",
    "type": "video",
    "video": {
      "link": "https://api.ycloud.com/v2/whatsapp/media/download/5926236...",
      "id": "592623615738103",
      "sha256": "LeRpQJq/h4HTjm...",
      "mime_type": "video/mp4"
    }
  }
}'

Response

Acknowledge the delivery after durably accepting the event.

HTTP/1.1 200 OK

Explanation

The video.link can be directly accessed in a few minutes for the convenience of the consumer, but you should always include an X-API-Key header to download this file within 30 days.

Outbound Audio message

In this case, your webhook endpoint received an outbound audio message sent by a business customer to a WhatsApp user with the WhatsApp Business app or supported companion device.:

Contains audio sent before.

Request

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEVCy8eNqD9EvcFI",
  "type": "whatsapp.smb.message.echoes",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "status": "sent",
    "from": "BUSINESS-PHONE-NUMBER",
    "to": "CUSTOMER-PHONE-NUMBER",
    "toUserId": "US.13491208655302741918",
    "toParentUserId": "US.1181579921288684483",
    "customerProfile": {
      "username": "@joee"
    },
    "wabaId": "WABA-ID",
    "createTime": "2022-03-01T12:00:00.000Z",
    "sendTime": "2022-03-01T12:00:01.000Z",
    "bizType": "whatsapp",
    "type": "audio",
    "audio": {
      "link": "https://api.ycloud.com/v2/whatsapp/media/download/5926236...",
      "id": "592623615738103",
      "sha256": "LeRpQJq/h4HTjm...",
      "mime_type": "audio/ogg; codecs=opus"
    }
  }
}'

Response

Acknowledge the delivery after durably accepting the event.

HTTP/1.1 200 OK

Explanation

The audio.link can be directly accessed in a few minutes for the convenience of the consumer, but you should always include an X-API-Key header to download this file within 30 days.

Outbound Document message

In this case, your webhook endpoint received an outbound document message sent by a business customer to a WhatsApp user with the WhatsApp Business app or supported companion device.:

Contains document sent before.

Request

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEVCy8eNqD9EvcFI",
  "type": "whatsapp.smb.message.echoes",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "status": "sent",
    "from": "BUSINESS-PHONE-NUMBER",
    "to": "CUSTOMER-PHONE-NUMBER",
    "toUserId": "US.13491208655302741918",
    "toParentUserId": "US.1181579921288684483",
    "customerProfile": {
      "username": "@joee"
    },
    "wabaId": "WABA-ID",
    "createTime": "2022-03-01T12:00:00.000Z",
    "sendTime": "2022-03-01T12:00:01.000Z",
    "bizType": "whatsapp",
    "type": "document",
    "document": {
      "link": "https://api.ycloud.com/v2/whatsapp/media/download/5926236...",
      "id": "592623615738103",
      "caption": "图片",
      "sha256": "LeRpQJq/h4HTjm...",
      "mime_type": "image/jpeg"
    }
  }
}'

Response

Acknowledge the delivery after durably accepting the event.

HTTP/1.1 200 OK

Explanation

The document.link can be directly accessed in a few minutes for the convenience of the consumer, but you should always include an X-API-Key header to download this file within 30 days.

Business App message created

Use whatsapp.smb.message.created when a WhatsApp Business App message is sent.

Request

{
  "id": "evt_example_smb_created",
  "type": "whatsapp.smb.message.created",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+16315551111",
    "to": "+16315552222",
    "type": "text",
    "text": {
      "body": "Your order is ready for pickup."
    },
    "status": "sent",
    "createTime": "2026-10-08T12:00:00.000Z",
    "sendTime": "2026-10-08T12:00:00.000Z"
  }
}

Response

Acknowledge the delivery after durably accepting the event.

HTTP/1.1 200 OK

Explanation

Read the outbound message from whatsappMessage. Its type selects the content object; this text example uses text.body. Route this event separately from whatsapp.smb.message.echoes while sharing message parsing where appropriate. These are Business App coexistence events, not Meta Business Agent echo events.

Getting Started

Guides

Endpoints

Webhooks

WhatsApp Business App Sent Message Sync Webhook Examples

What it is

Before you begin

How it works

Request

Response

Outbound Text message

Request

Response

Explanation

Outbound Image message

Request

Response

Explanation

Outbound Video message

Request

Response

Explanation

Outbound Audio message

Request

Response

Explanation

Outbound Document message

Request

Response

Explanation

Business App message created

Request

Response

Explanation

​What it is

​Before you begin

​How it works

​Request

​Response

​Outbound Text message

​Request

​Response

​Explanation

​Outbound Image message

​Request

​Response

​Explanation

​Outbound Video message

​Request

​Response

​Explanation

​

​Outbound Audio message

​Request

​Response

​Explanation

​Outbound Document message

​Request

​Response

​Explanation

​Business App message created

​Request

​Response

​Explanation

What it is

Before you begin

How it works

Request

Response

Outbound Text message

Request

Response

Explanation

Outbound Image message

Request

Response

Explanation

Outbound Video message

Request

Response

Explanation

Outbound Audio message

Request

Response

Explanation

Outbound Document message

Request

Response

Explanation

Business App message created

Request

Response

Explanation