WhatsApp 群组状态更新 Webhook 示例

如需查看完整的 Schema 衍生目录，请参阅所有示例。

概述

处理 WhatsApp 群组封禁状态更新。

准备工作

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

工作原理

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

请求

以下场景展示了发送到您的 Webhook URL 的请求。将事件 id 视为投递标识符，并使用 type 路由有效负载。

响应

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

HTTP/1.1 200 OK

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

群组被封禁

当 WhatsApp 群组被封禁时，您将收到包含以下有效负载结构的 Webhook：

请求

{
  "id": "evt_group_status_123",
  "type": "whatsapp.group.status_update",
  "apiVersion": "v2",
  "createTime": "2026-05-13T00:00:00.000Z",
  "whatsappGroup": {
    "wabaId": "123456789012345",
    "field": "group_status_update",
    "type": "group_suspend",
    "status": "suspended",
    "groupId": "Y2FwaV9ncm91cDpFWEFNUExFX0dST1VQX0lE",
    "webhookTime": "2026-05-13T00:00:00.000Z"
  }
}

响应

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

HTTP/1.1 200 OK

说明

根据 type 路由事件，通过 id 进行去重，并将耗时或容易失败的任务转移到异步处理器。

群组封禁已解除

当 WhatsApp 群组封禁被解除时，您将收到包含以下有效负载结构的 Webhook：

请求

{
  "id": "evt_group_status_124",
  "type": "whatsapp.group.status_update",
  "apiVersion": "v2",
  "createTime": "2026-05-13T00:00:00.000Z",
  "whatsappGroup": {
    "wabaId": "123456789012345",
    "field": "group_status_update",
    "type": "group_suspend_cleared",
    "status": "suspend_cleared",
    "groupId": "Y2FwaV9ncm91cDpFWEFNUExFX0dST1VQX0lE",
    "webhookTime": "2026-05-13T00:00:00.000Z"
  }
}

响应

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

HTTP/1.1 200 OK

说明

type：群组封禁状态事件固定为 whatsapp.group.status_update
whatsappGroup：包含群组封禁状态详情
- field：固定为 group_status_update
- type：状态事件类型，为 group_suspend 或 group_suspend_cleared
- status：标准化群组状态，为 suspended 或 suspend_cleared
- groupId：WhatsApp 群组 ID
- webhookTime：WhatsApp 触发此 Webhook 的时间

开始使用

指南

接口

Webhooks

WhatsApp 群组状态更新 Webhook 示例

概述

准备工作

工作原理

请求

响应

群组被封禁

请求

响应

说明

群组封禁已解除

请求

响应

说明

​概述

​准备工作

​工作原理

​请求

​响应

​群组被封禁

​请求

​响应

​说明

​群组封禁已解除

​请求

​响应

​说明

概述

准备工作

工作原理

请求

响应

群组被封禁

请求

响应

说明

群组封禁已解除

请求

响应

说明