> ## 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 Flow Webhook 示例

> 处理 WhatsApp Flow 状态变更事件。

<Note>有关基于 schema 生成的完整目录，请参阅[所有示例](/zh/api-reference/guides/examples/webhook-examples/webhook-payload-examples)。</Note>

## 功能简介

处理 WhatsApp Flow 状态变更事件。

## 准备工作

* 在您的应用程序中创建一个公开的 HTTPS 端点。
* 针对您需要的事件类型配置 YCloud Webhook 端点。
* 安全存储端点签名密钥。
* 确保事件处理具备幂等性。

## 工作原理

当事件发生时，YCloud 会发送 HTTP `POST` 请求。请验证签名，持久化记录该事件，返回 `2xx` 响应，并异步处理耗时任务。

## 请求

以下场景展示了发送到您的 Webhook URL 的请求。请将事件 `id` 作为投递标识符，并使用 `type` 对载荷进行路由。

## 响应

接收事件后返回 `2xx` 状态。

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

<Note>有关端点设置、签名验证和重试机制，请参阅[配置 Webhook](/zh/api-reference/guides/api-fundamentals/configure-webhooks)。</Note>

## Flow 状态变更

当 WhatsApp Flow 更改其状态（例如从 DRAFT 变为 PUBLISHED）时，您将收到包含以下载荷结构的 Webhook：

### 请求

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "type": "whatsapp.flow.status_change",
  "id": "evt_1234567890abcdef",
  "apiVersion": "v2",
  "createTime": "2025-09-11T07:24:52.000Z",
  "flowChanges": {
    "flowId": "1097420589034000",
    "wabaId": "123456789012345",
    "message": "Flow Webhook 3 changed status from DRAFT to PUBLISHED",
    "oldStatus": "DRAFT",
    "newStatus": "PUBLISHED"
  }
}
```

### 响应

持久化接收事件后确认投递。

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### 字段说明

* **type**：对于 Flow 状态变更事件，固定为 `whatsapp.flow.status_change`
* **flowChanges**：包含 Flow 状态变更详情
  * **flowId**：发生状态变更的 Flow 的唯一 ID
  * **wabaId**：与该 Flow 关联的 WhatsApp 商业账户 ID
  * **message**：状态变更的可读描述
  * **oldStatus**：Flow 的先前状态
  * **newStatus**：Flow 的当前状态

### 常见 Flow 状态值

* `DRAFT`
* `PUBLISHED`
* `DEPRECATED`
* `BLOCKED`
* `THROTTLED`


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