> ## 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 群组设置更新 Webhook 示例

> 处理 WhatsApp 群组主题和描述的更新。

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

## 概述

处理 WhatsApp 群组主题和描述的更新。

## 准备工作

* 在您的应用程序中创建一个公开的 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>

<br />

## 设置已更新

当 WhatsApp 群组设置成功更新时，您将收到包含以下有效负载结构的 Webhook：

### 请求

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "evt_group_settings_123",
  "type": "whatsapp.group.settings_update",
  "apiVersion": "v2",
  "createTime": "2026-05-13T00:00:00.000Z",
  "whatsappGroup": {
    "wabaId": "123456789012345",
    "field": "group_settings_update",
    "type": "group_settings_update",
    "requestId": "REQ_2",
    "status": "updated",
    "groupId": "Y2FwaV9ncm91cDpFWEFNUExFX0dST1VQX0lE",
    "subject": "Updated Purchase Inquiry",
    "description": "Updated group description.",
    "settings": [
      {
        "name": "group_subject",
        "text": "Updated Purchase Inquiry",
        "updateSuccessful": true
      },
      {
        "name": "group_description",
        "text": "Updated group description.",
        "updateSuccessful": true
      }
    ],
    "webhookTime": "2026-05-13T00:00:00.000Z"
  }
}
```

### 响应

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

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

### 说明

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

## 设置更新失败

当 WhatsApp 群组设置更新失败或部分失败时，您将收到包含以下有效负载结构的 Webhook：

### 请求

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "evt_group_settings_124",
  "type": "whatsapp.group.settings_update",
  "apiVersion": "v2",
  "createTime": "2026-05-13T00:00:00.000Z",
  "whatsappGroup": {
    "wabaId": "123456789012345",
    "field": "group_settings_update",
    "type": "group_settings_update",
    "requestId": "REQ_SETTINGS",
    "status": "failed",
    "groupId": "Y2FwaV9ncm91cDpFWEFNUExFX0dST1VQX0lE",
    "subject": "New subject",
    "settings": [
      {
        "name": "group_subject",
        "text": "New subject",
        "updateSuccessful": false,
        "errors": [
          {
            "code": 131201,
            "title": "Invalid group subject"
          }
        ]
      }
    ],
    "webhookTime": "2026-05-13T00:00:00.000Z"
  }
}
```

### 响应

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

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

### 说明

* **type**：对于群组设置事件始终为 `whatsapp.group.settings_update`
* **whatsappGroup**：包含群组设置更新结果详情
  * **field**：始终为 `group_settings_update`
  * **type**：始终为 `group_settings_update`
  * **requestId**：异步群组设置 API 操作返回的请求 ID
  * **status**：标准化的设置更新状态，取值为 `updated` 或 `failed`
  * **groupId**：WhatsApp 群组 ID
  * **subject** 和 **description**：群组文本设置（如果存在）
  * **settings**：每项设置的更新结果。`name` 可以是 `profile_picture`、`group_subject` 或 `group_description`
  * **settings\[].updateSuccessful**：指示单个设置更新是否成功
  * **settings\[].errors**：WhatsApp 针对单个设置返回的错误

<br />


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