> ## 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.

# 联系人属性变更 Webhook 示例

> 处理联系人属性变更事件。

<Note>如需查看完整的 Schema 衍生目录，请参阅[所有示例](/zh/api-reference/guides/examples/webhook-examples/webhook-payload-examples)。</Note>

## 概述

处理联系人属性变更事件。

## 准备工作

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

当联系人的属性发生修改时触发。Webhook 有效负载包含有关哪些属性发生变更的信息，包括其旧值和新值。

## 标签变更示例（添加标签）

### 请求

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "evt_1234567892",
  "type": "contact.attributes_changed",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "contactAttributesChanged": {
    "id": "1824266594102064128",
    "updateTime": "2024-01-01T12:00:00.000Z",
    "changedAttributes": {
      "tags": {
        "oldValue": ["premium", "newsletter"],
        "newValue": ["premium", "newsletter", "vip"],
        "extra": [
          {
            "action": "ADDED",
            "id": "686dd294334be8606a5bf312",
            "value": "vip"
          }
        ]
      }
    }
  }
}
```

### 响应

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

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

### 说明

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

## 标签变更示例（移除标签）

### 请求

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "evt_1234567893",
  "type": "contact.attributes_changed",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "contactAttributesChanged": {
    "id": "1824266594102064128",
    "updateTime": "2024-01-01T12:00:00.000Z",
    "changedAttributes": {
      "tags": {
        "oldValue": ["premium", "newsletter", "vip"],
        "newValue": ["premium", "newsletter"],
        "extra": [
          {
            "action": "REMOVED",
            "id": "686dd294334be8606a5bf312",
            "value": "vip"
          }
        ]
      }
    }
  }
}
```

### 响应

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

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

### 说明

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

## 变更示例

### 请求

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "evt_1234567900",
  "type": "contact.attributes_changed",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "contactAttributesChanged": {
    "id": "1824266594102064128",
    "updateTime": "2024-01-01T12:00:00.000Z",
    "changedAttributes": {
      "waba_id": {
        "oldValue": "waba_old_123456",
        "newValue": "waba_new_789012",
        "extra": [
          {
            "action": "CHANGED"
          }
        ]
      }
    }
  }
}
```

### 响应

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

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

### 说明

* **正确的结构**：`contactAttributesChanged` 对象包含三个必填字段：`id`、`updateTime` 和 `changedAttributes`。
* **已变更的属性**：`changedAttributes` 字段是一个对象，其中每个键是属性名称，值为 `ContactAttributeChange` 对象。
* **事件属性配置**：启用 `contact.attributes_changed` 事件时，必须在 Webhook 端点中配置 `eventProperties` 字段，以指定哪些属性应包含在 Webhook 有效负载中。
* **属性类型**：`oldValue` 和 `newValue` 字段可以包含不同的数据类型：
  * String：文本值
  * Number：数值（整数或小数）
  * Boolean：布尔值（true/false）
  * Array：字符串数组
  * Object：包含嵌套属性的复杂对象
  * Null：当属性被移除或未设置时
* **标签变更**：对于标签属性，`extra` 字段提供了有关添加或移除哪些标签的详细信息，包括其 ID 和值。
* **空值**：当属性被移除或设置为 null 时，`newValue` 将为 `null`。当属性为新添加时，`oldValue` 可能为 `null`。
* **自定义属性**：自定义属性与标准属性一样包含在 `changedAttributes` 对象中，以其自定义键作为属性名称。
* **变更检测**：仅实际发生变更的属性才会包含在 `changedAttributes` 对象中。
* **额外字段**：`extra` 字段是可选的，主要用于标签相关的变更，以提供关于所执行特定操作的额外上下文。


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