WhatsApp Flow Webhook 示例

有关基于 schema 生成的完整目录，请参阅所有示例。

功能简介

处理 WhatsApp Flow 状态变更事件。

准备工作

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

工作原理

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

请求

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

响应

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

HTTP/1.1 200 OK

有关端点设置、签名验证和重试机制，请参阅配置 Webhook。

Flow 状态变更

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

请求

{
  "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/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

开始使用

指南

接口

Webhooks

WhatsApp Flow Webhook 示例

功能简介

准备工作

工作原理

请求

响应

Flow 状态变更

请求

响应

字段说明

常见 Flow 状态值

​功能简介

​准备工作

​工作原理

​请求

​响应

​Flow 状态变更

​请求

​响应

​字段说明

​常见 Flow 状态值

功能简介

准备工作

工作原理

请求

响应

Flow 状态变更

请求

响应

字段说明

常见 Flow 状态值