> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# WhatsApp Business App Sent Message Sync Webhook Examples

> Handle WhatsApp Business App sent-message synchronization events.

<Note>For the exhaustive schema-derived catalog, see [all examples](/en/api-reference/guides/examples/webhook-examples/webhook-payload-examples).</Note>

## 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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

<Note>For endpoint setup, signature validation, and retry behavior, see [Configure webhooks](/en/api-reference/guides/api-fundamentals/configure-webhooks).</Note>

## 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 supported companion device.:

* Contains plain text sent before.
* Contains the mentioned message information in `context`.

### Request

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.