> ## 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 для обновлений участников групп WhatsApp

> Обработка обновлений участников групп WhatsApp и запросов на вступление.

<Note>Полный каталог на основе схемы см. в разделе [все примеры](/ru/api-reference/guides/examples/webhook-examples/webhook-payload-examples).</Note>

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

Обработка обновлений участников групп WhatsApp и запросов на вступление.

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

* Создайте публичный эндпоинт 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](/ru/api-reference/guides/api-fundamentals/configure-webhooks).</Note>

<br />

## Участник добавлен

Когда участник добавляется в группу WhatsApp, вы получите webhook со следующей структурой полезной нагрузки:

### Запрос

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "evt_group_participants_123",
  "type": "whatsapp.group.participants_update",
  "apiVersion": "v2",
  "createTime": "2026-05-13T00:00:00.000Z",
  "whatsappGroup": {
    "wabaId": "123456789012345",
    "field": "group_participants_update",
    "type": "group_participants_add",
    "status": "added",
    "groupId": "Y2FwaV9ncm91cDpFWEFNUExFX0dST1VQX0lE",
    "reason": "invite_link",
    "waId": "16315551111",
    "recipientUserId": "US.abc123",
    "parentRecipientUserId": "US.parent123",
    "addedParticipants": [
      {
        "input": "US.abc123",
        "waId": "16315551111",
        "recipientUserId": "US.abc123",
        "parentRecipientUserId": "US.parent123"
      }
    ],
    "customerProfile": {
      "name": "John Doe",
      "username": "john_doe"
    },
    "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_participants_124",
  "type": "whatsapp.group.participants_update",
  "apiVersion": "v2",
  "createTime": "2026-05-13T00:00:00.000Z",
  "whatsappGroup": {
    "wabaId": "123456789012345",
    "field": "group_participants_update",
    "type": "group_join_request_created",
    "status": "requested",
    "groupId": "Y2FwaV9ncm91cDpFWEFNUExFX0dST1VQX0lE",
    "reason": "admin_approval",
    "joinRequestId": "join-request-id",
    "waId": "16315551111",
    "recipientUserId": "US.abc123",
    "parentRecipientUserId": "US.parent123",
    "webhookTime": "2026-05-13T00:00:00.000Z",
    "customerProfile": {
      "name": "John Doe",
      "username": "john_doe"
    }
  }
}
```

### Ответ

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

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

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

Маршрутизируйте событие по полю `type`, выполняйте дедупликацию по `id` и передавайте длительные или подверженные сбоям задачи асинхронному обработчику.

## Ошибка удаления участника

Если удаление одного или нескольких участников завершилось ошибкой или выполнено частично, вы получите webhook со следующей структурой полезной нагрузки:

### Запрос

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "evt_group_participants_125",
  "type": "whatsapp.group.participants_update",
  "apiVersion": "v2",
  "createTime": "2026-05-13T00:00:00.000Z",
  "whatsappGroup": {
    "wabaId": "123456789012345",
    "field": "group_participants_update",
    "type": "group_participants_remove",
    "requestId": "REQ_REMOVE",
    "status": "failed",
    "groupId": "Y2FwaV9ncm91cDpFWEFNUExFX0dST1VQX0lE",
    "initiatedBy": "business",
    "removedParticipants": [
      {
        "input": "16315551111"
      }
    ],
    "failedParticipants": [
      {
        "input": "16315552222",
        "errors": [
          {
            "code": 131212,
            "title": "Participant cannot be removed"
          }
        ]
      }
    ],
    "errors": [
      {
        "title": "Not all participants were removed"
      }
    ],
    "webhookTime": "2026-05-13T00:00:00.000Z"
  }
}
```

### Ответ

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

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

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

* **type**: всегда `whatsapp.group.participants_update` для событий участников группы и запросов на вступление
* **whatsappGroup**: содержит подробные сведения об обновлении участников группы или запроса на вступление
  * **field**: всегда `group_participants_update`
  * **type**: тип события участника, например `group_participants_add`, `group_participants_remove`, `group_join_request_created` или `group_join_request_revoked`
  * **status**: нормализованный статус события, например `added`, `removed`, `left`, `requested`, `revoked` или `failed`
  * **groupId**: идентификатор группы WhatsApp
  * **reason**: причина события участника или запроса на вступление
  * **joinRequestId**: идентификатор запроса на вступление, указывается для событий запросов на вступление
  * **initiatedBy**: указывает, кто инициировал событие удаления, например `business` или `participant`
  * **recipientUserId** и **parentRecipientUserId**: идентификаторы пользователя в контексте бизнеса для затронутого участника
  * **addedParticipants**, **removedParticipants** и **failedParticipants**: сведения на уровне участников для пакетных обновлений или обновлений с частичным результатом

<br />


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