Настройка вебхуков

Что это такое

Webhooks — это HTTPS-запросы, которые YCloud отправляет вашему приложению при изменении статуса доставки сообщений, входящих сообщений, контактов, шаблонов, вызовов и других ресурсов.

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

Сохраните свой API-ключ YCloud в YCLOUD_API_KEY.
Разверните общедоступную конечную точку HTTPS.
Сохраняйте исходное тело запроса (raw body) для проверки подписи.
Определите, какие типы событий требуются вашему приложению.

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

Создайте конечную точку Webhook и подпишите ее на нужные типы событий.
Сохраните возвращенный secret конечной точки.
YCloud отправляет запрос события на вашу конечную точку.
Проверьте YCloud-Signature, прежде чем доверять запросу.
Своевременно верните ответ 2xx.
Обрабатывайте событие идемпотентно, так как доставка может повторяться.

Запрос

Создайте конечную точку с помощью POST /webhookEndpoints.

Поля запроса

Поле	Обязательное	Описание
`url`	Да	Публичный HTTPS URL, принимающий запросы событий. Не более 500 символов.
`enabledEvents`	Да	Типы событий, доставляемые на эту конечную точку.
`eventProperties`	Условно	Свойства, включаемые для выбранных типов событий. Обязательно для `contact.attributes_changed`.
`description`	Нет	Описание конечной точки. Не более 400 символов.
`status`	Нет	Начальный статус конечной точки.

Пример запроса

curl --request POST https://api.ycloud.com/v2/webhookEndpoints \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "url": "https://example.com/webhooks/ycloud",
    "enabledEvents": [
      "whatsapp.inbound_message.received",
      "whatsapp.message.updated",
      "sms.message.updated"
    ],
    "description": "Production messaging events"
}'

Подписка на события echo и handover

Для Agents, подключенных через общедоступный REST API, создайте конечную точку со следующими подписками. Agents, созданные через Console, не отправляют эти три события. Чтобы изменить существующую конечную точку, сохраните подписки на события, которые вам по-прежнему необходимы.

curl --request POST https://api.ycloud.com/v2/webhookEndpoints \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "url": "https://example.com/webhooks/ycloud",
    "enabledEvents": [
      "whatsapp.echo_message.created",
      "whatsapp.echo_message.updated",
      "whatsapp.meta_business_agent.handover.updated",
      "whatsapp.inbound_message.received"
    ],
    "description": "API Agent echo and handover events"
  }'

Оба типа событий echo передают стандартную полезную нагрузку whatsappMessage в формате сообщения. Событие handover передает whatsappMetaBusinessAgent и сохраняет информацию об Agent/управлении. Они не используют контракт whatsapp.smb.message.echoes WhatsApp Business App. См. сведения о событиях echo и handover для определений полей, примеров, порядка и ограничений корреляции handover.

Подписка на события сообщений Messenger

Тип события	Полезная нагрузка	Когда происходит
`messenger.inbound_message.received`	`messengerInboundMessage`	Клиент отправляет обычное текстовое сообщение.
`messenger.inbound_message.updated`	`messengerInboundMessage`	Клиент редактирует сохраненное входящее текстовое сообщение.
`messenger.message.updated`	`messengerMessage`	Доступен результат исходящей отправки или сопоставленный отчет о доставке сообщения.
`messenger.message_reaction.updated`	`messengerMessageReaction`	Клиент ставит или удаляет реакцию на сообщение.

Укажите необходимые имена событий в enabledEvents при создании или обновлении конечной точки. Например, чтобы подписаться на все четыре:

{
  "url": "https://example.com/webhooks/ycloud",
  "enabledEvents": [
    "messenger.inbound_message.received",
    "messenger.inbound_message.updated",
    "messenger.message.updated",
    "messenger.message_reaction.updated"
  ]
}

В Dashboard новая конечная точка создается без выбранных событий. При выборе категории Messenger выбираются все доступные в ней события, включая редактирование и реакции. Затем вы можете отменить выбор отдельных событий. Существующие подписки не включают автоматически новые события редактирования или реакций. При обновлении конечной точки обязательно сохраняйте подписки, которые вам все еще нужны. При редактировании сохраняются те же messengerInboundMessage.id и metaMessageId, заменяется text.body и добавляются editCount и editTime. Поля сообщения sendTime и createTime остаются неизменными; оболочка события createTime указывает время редактирования. В неотредактированных сообщениях поля редактирования отсутствуют. Обновляется только существующее входящее сообщение. Более ранние правки игнорируются; недостающие сообщения и история правок не восстанавливаются. Сопоставляйте обновления по ID сообщения и используйте накопительный счетчик, чтобы предотвратить применение более старого текста поверх более новой версии. Повторные попытки источника могут создавать другой ID события для той же сохраненной правки. См. пример редактирования входящего сообщения. События реакций содержат pageId, psid отреагировавшего клиента, целевой metaMessageId и action (react или unreact). Необязательные поля reaction и emoji могут отсутствовать, особенно для unreact. Реакция не меняет статус доставки сообщения. Целевое сообщение может быть создано вне YCloud API, поэтому событие не требует локальной записи сообщения и не содержит локальный ID сообщения. Поле события createTime сохраняет время исходного взаимодействия. Повторные попытки доставки клиенту сохраняют его id события и полезную нагрузку. Обработка обратного вызова источником может приводить к созданию другого ID события для повторяющегося взаимодействия; не используйте ID событий в качестве идентификаторов реакций или сообщений. См. примеры полезной нагрузки реакций для обоих действий.

Ответ

В ответе возвращается созданная конечная точка и ее secret для подписи. Храните секрет в безопасности. YCloud использует его для создания подписей Webhook.

Пример ответа

{
  "id": "WEBHOOK_ENDPOINT_ID",
  "url": "https://example.com/webhooks/ycloud",
  "enabledEvents": [
    "whatsapp.inbound_message.received",
    "whatsapp.message.updated",
    "sms.message.updated"
  ],
  "description": "Production messaging events",
  "status": "active",
  "secret": "whsec_REPLACE_WITH_RETURNED_SECRET",
  "createTime": "2026-07-16T12:00:00.000Z",
  "updateTime": "2026-07-16T12:00:00.000Z"
}

Поля ответа

Поле	Описание
`id`	Идентификатор эндпоинта Webhook, используемый для получения, обновления, удаления или ротации секрета эндпоинта.
`url`	URL назначения для доставки событий.
`enabledEvents`	Включенные в данный момент типы событий.
`status`	Текущее состояние эндпоинта.
`secret`	Секрет, используемый для проверки `YCloud-Signature`. Храните его в безопасности.
`createTime`, `updateTime`	Временные метки эндпоинта в формате RFC 3339.

Получение событий

Запрос события

YCloud отправляет JSON-объект события на настроенный url. Событие содержит общие поля, такие как id, type, apiVersion и createTime, а также полезную нагрузку, зависящую от типа события. Ваш обработчик должен:

Считывать необработанное тело запроса (raw request body).
Проверять заголовок YCloud-Signature с помощью секрета эндпоинта перед тем, как доверять полезной нагрузке.
Своевременно возвращать успешный ответ 2xx.
Переносить длительную обработку в очередь.
Обеспечивать идемпотентность обработки событий, чтобы повторная доставка не дублировала бизнес-действия.

Не парсите и не изменяйте тело запроса до валидации подписи. Используйте в точности те исходные байты, которые были получены вашим сервером.

Ответ получателя

Возвращайте успешный HTTP-ответ 2xx, как только подпись и запрос будут приняты. Тело ответа может быть пустым.

HTTP/1.1 204 No Content

Переносите длительную бизнес-обработку в очередь. Таймаут или ответ, отличный от 2xx, может привести к повторной отправке события со стороны YCloud, поэтому дедуплицируйте события по id.

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

Разверните событие, чтобы просмотреть полный пример его полезной нагрузки. Эти примеры взяты из спецификации OpenAPI для webhook. См. раздел все примеры полезной нагрузки вебхуков для каждого поддерживаемого типа событий.

Событие изменения атрибутов контакта

Пример полезной нагрузки при изменении атрибутов контакта

{
  "id": "evt_1234567890",
  "type": "contact.attributes_changed",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "contactAttributesChanged": {
    "id": "1824266594102064128",
    "updateTime": "2024-01-01T12:00:00.000Z",
    "changedAttributes": {
      "nickName": {
        "oldValue": "John Doe",
        "newValue": "Johnny Doe"
      },
      "email": {
        "oldValue": "john.doe@example.com",
        "newValue": "johnny.doe@example.com"
      },
      "tags": {
        "oldValue": [
          "premium",
          "newsletter"
        ],
        "newValue": [
          "premium",
          "newsletter",
          "vip"
        ],
        "extra": [
          {
            "action": "ADDED",
            "id": "686dd294334be8606a5bf312",
            "value": "vip"
          }
        ]
      }
    }
  }
}

Событие создания контакта

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

{
  "id": "evt_2345678901",
  "type": "contact.created",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "contactCreated": {
    "id": "1824266594102064128",
    "nickName": "John Doe",
    "realName": "John Smith",
    "phoneNumber": "+16315551111",
    "countryCode": "US",
    "countryName": "United States",
    "email": "john.doe@example.com",
    "sourceType": "api",
    "sourceId": "import_batch_123",
    "sourceUrl": "https://example.com/signup",
    "lastSeen": "2024-01-01T11:59:00.000Z",
    "lastConnectedNumber": "+16315552222",
    "ownerEmail": "owner@example.com",
    "tags": [
      "premium",
      "newsletter"
    ],
    "createTime": "2024-01-01T12:00:00.000Z",
    "updateTime": "2024-01-01T12:00:00.000Z",
    "blocked": false,
    "customAttributes": {
      "attr1": "value1",
      "attr2": "value2",
      "attr3": 123
    }
  }
}

Событие удаления контакта

Пример полезной нагрузки при удалении контакта

{
  "id": "evt_3456789012",
  "type": "contact.deleted",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "contactDeleted": {
    "id": "1824266594102064128",
    "nickName": "John Doe",
    "phoneNumber": "+16315551111",
    "updateTime": "2024-01-01T12:00:00.000Z"
  }
}

Событие отмены подписки клиентом

Пример полезной нагрузки при отмене подписки клиентом

{
  "id": "evt_3456789012",
  "type": "contact.unsubscribe.created",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "unsubscriberChanged": {
    "phoneNumber": "+16315551111",
    "source": "Whatsapp",
    "updateTime": "2024-01-01T12:00:00.000Z"
  }
}

Возобновление подписки клиентом

Пример полезной нагрузки при возобновлении подписки клиентом

{
  "id": "evt_3456789012",
  "type": "contact.unsubscribe.deleted",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "unsubscriberChanged": {
    "phoneNumber": "+16315551111",
    "source": "Whatsapp",
    "updateTime": "2024-01-01T12:00:00.000Z"
  }
}

Событие архивации шаблона WhatsApp

Пример полезной нагрузки при архивации шаблона WhatsApp

{
  "id": "evt_template_archived_123",
  "type": "whatsapp.template.reviewed",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "whatsappTemplate": {
    "id": "template-id",
    "officialTemplateId": "official-template-id",
    "wabaId": "whatsapp-business-account-id",
    "name": "sample_whatsapp_template",
    "language": "en",
    "category": "MARKETING",
    "status": "ARCHIVED",
    "statusUpdateEvent": "ARCHIVED",
    "createTime": "2024-01-01T12:00:00.000Z",
    "updateTime": "2024-01-01T12:00:00.000Z"
  }
}

Событие разархивации шаблона WhatsApp

Пример полезной нагрузки при разархивации шаблона WhatsApp. Статус шаблона является текущим статусом, возвращенным Meta, и не означает прохождение новой проверки на одобрение.

{
  "id": "evt_template_unarchived_123",
  "type": "whatsapp.template.reviewed",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "whatsappTemplate": {
    "id": "template-id",
    "officialTemplateId": "official-template-id",
    "wabaId": "whatsapp-business-account-id",
    "name": "sample_whatsapp_template",
    "language": "en",
    "category": "MARKETING",
    "status": "APPROVED",
    "statusUpdateEvent": "UNARCHIVED",
    "createTime": "2024-01-01T12:00:00.000Z",
    "updateTime": "2024-01-01T12:00:00.000Z"
  }
}

Событие соединения вызова WhatsApp

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

{
  "id": "evt_call_connect_123",
  "type": "whatsapp.call.connect",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "callingConnect": {
    "id": "6757b723960b25543b9ecc66",
    "wacid": "wacid.HBgNNjI4MTM2MTkwNTEzMxUCABIYIEF",
    "phoneId": "461269257068832",
    "from": "+6281361905133",
    "to": "+6283138205150",
    "direction": "USER_INITIATED",
    "dialTime": 1733826430000,
    "sdpType": "offer",
    "sdp": "v=0\r\no=- 1732169627243 2 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\na=group:BUNDLE audio\r\na=msid-semantic: WMS af3b01e3-eb42-4244-812e-db903c062ae7\r\na=ice-lite\r\nm=audio 3480 UDP/TLS/RTP/SAVPF 111 126\r\nc=IN IP4 31.13.87.130\r\na=rtcp:9 IN IP4 0.0.0.0\r\na=candidate:785588535 1 udp 2122260223 31.13.87.130 3480 typ host generation 0 network-cost 50\r\na=candidate:1906600321 1 udp 2122262783 2a03:2880:f217:d0:face:b00c:0:699c 3480 typ host generation 0 network-cost 50\r\na=ice-ufrag:CvRXRnInnWhQzLIE\r\na=ice-pwd:HGXUGAFI8wK6seuVknBT2Q==\r\na=fingerprint:sha-256 FB:56:A1:C5:37:35:6C:5C:1B:05:23:B0:DD:BB:2E:C9:5F:E4:70:61:7B:D9:1D:09:84:76:46:23:12:38:B7:01\r\na=setup:actpass\r\na=mid:audio\r\na=sendrecv\r\na=msid:af3b01e3-eb42-4244-812e-db903c062ae7 WhatsAppTrack1\r\na=rtcp-mux\r\na=rtpmap:111 opus/48000/2\r\na=rtcp-fb:111 transport-cc\r\na=fmtp:111 maxaveragebitrate=20000;maxplaybackrate=16000;minptime=20;sprop-maxcapturerate=16000;useinbandfec=1\r\na=rtpmap:126 telephone-event/8000\r\na=maxptime:20\r\na=ptime:20\r\na=ssrc:659928310 cname:WhatsAppAudioStream1\r\n"
  }
}

Событие завершения вызова WhatsApp

Пример полезной нагрузки при завершении вызова WhatsApp

{
  "id": "evt_6757b889a5a42d369ef48481",
  "type": "whatsapp.call.terminate",
  "apiVersion": "v2",
  "createTime": "2024-12-10T03:42:01.822Z",
  "callingTerminate": {
    "id": "6757b889960b25543b9ecc67",
    "wacid": "wacid.HBgNNjI4MTM2MTkwNTEzMxUCABIYIEFENjB",
    "phoneId": "461269257068832",
    "from": "+6281361905133",
    "to": "+6283138205150",
    "direction": "USER_INITIATED",
    "startTime": 1733734738000,
    "endTime": 1733734771000,
    "duration": 33,
    "status": "COMPLETED"
  }
}

Событие обновления статуса вызова WhatsApp

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

{
  "id": "evt_676e5ab57a9cb742d02d7646",
  "type": "whatsapp.call.status.updated",
  "apiVersion": "v2",
  "createTime": "2024-12-27T07:41:28.422Z",
  "callingStatusUpdated": {
    "wabaId": "188234691048809",
    "wacid": "wacid.HBgNNjI4MTM2MTkwNTEzMxUCABE",
    "status": "RINGING",
    "recipientPhone": "+6281361905133"
  }
}

См. раздел Полезные нагрузки событий Webhook для получения полной схемы Event и интерактивного справочника полезных нагрузок.

Ротация секрета эндпоинта

Выполните ротацию секрета в случае его компрометации или в соответствии с вашей политикой безопасности:

curl --request POST \
  https://api.ycloud.com/v2/webhookEndpoints/WEBHOOK_ENDPOINT_ID/rotateSecret \
  --header "X-API-Key: $YCLOUD_API_KEY"

Разверните новый секрет на вашем приемнике сразу после ротации.

Эндпоинт, который неоднократно не может принять уведомления, может перейти в статус pending и прекратить получение событий. Отслеживайте сбои доставки Webhook и статус эндпоинта.

Информацию о коде проверки подписи, интервалах повторных попыток и реализации приемника см. в статье Реализация приемника Webhook.

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

Руководства

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

Webhooks

Настройка вебхуков

Что это такое

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

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

Запрос

Поля запроса

Пример запроса

Подписка на события echo и handover

Подписка на события сообщений Messenger

Ответ

Пример ответа

Поля ответа

Получение событий

Запрос события

Ответ получателя

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

Ротация секрета эндпоинта

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

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

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

​Запрос

​Поля запроса

​Пример запроса

​Подписка на события echo и handover

​Подписка на события сообщений Messenger

​Ответ

​Пример ответа

​Поля ответа

​Получение событий

​Запрос события

​Ответ получателя

​Примеры стандартных полезных нагрузок

​Ротация секрета эндпоинта

Что это такое

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

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

Запрос

Поля запроса

Пример запроса

Подписка на события echo и handover

Подписка на события сообщений Messenger

Ответ

Пример ответа

Поля ответа

Получение событий

Запрос события

Ответ получателя

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

Ротация секрета эндпоинта