Перейти к основному содержанию

Что это такое

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

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

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

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

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

Запрос

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

Поля запроса

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

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

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

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

Укажите нужные имена событий в enabledEvents при создании или обновлении конечной точки. Например, чтобы подписаться на все четыре события:
В 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 события и его полезную нагрузку. Обработка обратного вызова (callback) источником может сгенерировать другой ID события для повторяющегося взаимодействия; не используйте ID событий в качестве идентификаторов реакций или сообщений. Примеры полезной нагрузки для обоих действий см. в reaction payload examples.

Ответ

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

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

Поля ответа

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

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

YCloud отправляет объект события JSON на настроенный url. Событие включает общие поля, такие как id, type, apiVersion и createTime, а также полезную нагрузку для конкретного типа события. Ваш обработчик должен:
  1. Считывать исходное тело запроса (raw body).
  2. Проверять заголовок YCloud-Signature с помощью секрета эндпоинта перед обработкой полезной нагрузки.
  3. Оперативно возвращать успешный ответ 2xx.
  4. Переносить медленную обработку в очередь.
  5. Обеспечивать идемпотентность обработки событий, чтобы повторная доставка не приводила к дублированию бизнес-действий.
Не парсите и не изменяйте тело запроса до проверки подписи. Используйте в точности те необработанные байты, которые были получены вашим сервером.

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

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

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

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

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

Выполняйте ротацию секрета в случае его компрометации или в соответствии с политикой безопасности:
Сразу после ротации разверните новый секрет на стороне вашего сервиса-получателя.
Эндпоинт, который систематически не может принимать уведомления, может перейти в статус pending и прекратить получение событий. Отслеживайте ошибки webhook и статус эндпоинта.
Код проверки подписи, интервалы повторных попыток и реализацию получателя см. в разделе Реализация получателя webhook.