> ## 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]
>
> Полный каталог на основе схемы см. в разделе [все примеры](https://docs.ycloud.com/ru/api-reference/guides/examples/webhook-examples/webhook-payload-examples).

## Что это такое

Обработка событий `contact.attributes_changed` и `contact.note.updated`.

## Перед началом работы

* Создайте общедоступную конечную точку HTTPS в вашем приложении.
* Настройте конечную точку Webhook в YCloud для необходимых типов событий.
* Обеспечьте безопасное хранение секрета подписи конечной точки.
* Сделайте обработку событий идемпотентной.

## Как это работает

YCloud отправляет HTTP-запрос `POST` при возникновении события. Проверьте подпись, надежно сохраните событие, верните ответ `2xx` и обработайте длительные задачи асинхронно.

## Запрос

Приведенные ниже сценарии демонстрируют запросы, доставляемые на ваш URL Webhook. Используйте поле события `id` как идентификатор доставки, а `type` — для маршрутизации полезной нагрузки.

## Ответ

Верните статус `2xx` после успешного принятия события.

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

> [!NOTE]
>
> Информацию о настройке конечной точки, проверке подписи и механизме повторных попыток см. в разделе [Настройка Webhook](https://docs.ycloud.com/ru/api-reference/guides/api-fundamentals/configure-webhooks.md).

Происходит при изменении атрибутов контакта. Полезная нагрузка 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` необходимо настроить поле `eventProperties` в вашей конечной точке Webhook, чтобы указать, какие атрибуты должны быть включены в полезную нагрузку Webhook.
* **Типы атрибутов**: поля `oldValue` и `newValue` могут содержать различные типы данных:
  * String: текстовые значения
  * Number: числовые значения (целые или десятичные)
  * Boolean: логические значения (true/false)
  * Array: массивы строк
  * Object: сложные объекты с вложенными свойствами
  * Null: когда атрибут удален или сброшен
* **Изменения тегов**: для атрибутов тегов поле `extra` предоставляет подробную информацию о том, какие теги были добавлены или удалены, включая их идентификаторы и значения.
* **Значения Null**: когда атрибут удален или установлен в null, `newValue` будет `null`. Когда атрибут добавляется впервые, `oldValue` может быть `null`.
* **Пользовательские атрибуты**: пользовательские атрибуты включаются в объект `changedAttributes` так же, как и стандартные атрибуты, где их пользовательские ключи выступают в качестве имен атрибутов.
* **Определение изменений**: в объект `changedAttributes` включаются только те атрибуты, которые действительно изменились.
* **Дополнительное поле**: поле `extra` является необязательным и используется преимущественно для изменений, связанных с тегами, предоставляя дополнительный контекст о выполненных действиях.

## Заметка контакта обновлена

Используйте `contact.note.updated`, когда обновляется заметка контакта.

### Запрос

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "evt_2234567890abcdef12345678",
  "type": "contact.note.updated",
  "apiVersion": "v2",
  "createTime": "2024-01-02T12:00:00.000Z",
  "contactNote": {
    "id": "6a3de646e18f344f743aaa4d",
    "contactId": "1824266594102064128",
    "username": "alice_01",
    "phoneNumber": "+16315551111",
    "content": "Customer now prefers afternoon follow-up.",
    "createTime": "2024-01-01T12:00:00.000Z",
    "updateTime": "2024-01-02T12:00:00.000Z"
  }
}
```

### Ответ

Подтвердите доставку после надежного принятия события.

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

### Пояснение

Используйте `contactNote.id` для идентификации заметки и `contactId` для идентификации связанного с ней контакта. Поля `username` и `phoneNumber` описывают контакт и могут иметь значение null. Полезная нагрузка содержит моментальный снимок заметки для клиента, включая `content`, без внутренних идентификаторов оператора.


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