Примеры Webhook для обновлений участников групп WhatsApp

Полный каталог на основе схемы см. в разделе все примеры.

Что это такое

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

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

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

Принцип работы

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

Запрос

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

Ответ

Возвращайте статус 2xx после принятия события.

HTTP/1.1 200 OK

Информацию о настройке эндпоинта, проверке подписи и механизме повторных попыток см. в разделе Настройка webhook.

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

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

Запрос

{
  "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/1.1 200 OK

Пояснение

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

Запрос на вступление создан

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

Запрос

{
  "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/1.1 200 OK

Пояснение

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

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

Запрос

{
  "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/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: сведения на уровне участников для пакетных обновлений или обновлений с частичным результатом

Начало работы

Руководства

Конечные точки

Webhooks

Примеры Webhook для обновлений участников групп WhatsApp

Что это такое

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

Принцип работы

Запрос

Ответ

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

Запрос

Ответ

Пояснение

Запрос на вступление создан

Запрос

Ответ

Пояснение

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

Запрос

Ответ

Пояснение

​Что это такое

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

​Принцип работы

​Запрос

​Ответ

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

​Запрос

​Ответ

​Пояснение

​Запрос на вступление создан

​Запрос

​Ответ

​Пояснение

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

​Запрос

​Ответ

​Пояснение

Что это такое

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

Принцип работы

Запрос

Ответ

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

Запрос

Ответ

Пояснение

Запрос на вступление создан

Запрос

Ответ

Пояснение

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

Запрос

Ответ

Пояснение