Что это такое
Webhooks — это HTTPS-запросы, которые YCloud отправляет в ваше приложение при изменении статуса доставки сообщений, получении входящих сообщений, изменении контактов, шаблонов, вызовов и других ресурсов.Перед началом работы
- Сохраните ваш API-ключ YCloud в
YCLOUD_API_KEY. - Разверните общедоступную конечную точку HTTPS.
- Сохраняйте исходное тело запроса (raw request body) для проверки подписи.
- Определите, какие типы событий требуются вашему приложению.
Принцип работы
- Создайте конечную точку Webhook и подпишите её на нужные типы событий.
- Сохраните возвращённый параметр конечной точки
secret. - YCloud отправляет запрос с событием на вашу конечную точку.
- Проверьте
YCloud-Signature, прежде чем доверять запросу. - Своевременно возвращайте ответ
2xx. - Обрабатывайте событие идемпотентно, так как доставка может повторяться.
Запрос
Создайте конечную точку с помощьюPOST /webhookEndpoints.
Поля запроса
Пример запроса
Подписка на события echo и handover
Для агентов, подключённых через Public REST API, создайте конечную точку со следующими подписками. Агенты, созданные в консоли, эти три события не генерируют. Чтобы изменить существующую конечную точку, сохраните все подписки на события, которые вам всё ещё нужны.whatsappMessage. Событие handover передаёт whatsappMetaBusinessAgent и сохраняет информацию об агенте/управлении. Они не используют контракт WhatsApp Business App whatsapp.smb.message.echoes. См. подробности о событиях echo и handover для ознакомления с определениями полей, примерами, порядком следования и ограничениями корреляции handover.
Подписка на события сообщений Messenger
Укажите нужные имена событий в
enabledEvents при создании или обновлении конечной точки. Например, чтобы подписаться на все четыре события:
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, а также полезную нагрузку для конкретного типа события.
Ваш обработчик должен:
- Считывать исходное тело запроса (raw body).
- Проверять заголовок
YCloud-Signatureс помощью секрета эндпоинта перед обработкой полезной нагрузки. - Оперативно возвращать успешный ответ
2xx. - Переносить медленную обработку в очередь.
- Обеспечивать идемпотентность обработки событий, чтобы повторная доставка не приводила к дублированию бизнес-действий.
Ответ получателя
Возвращайте успешный HTTP-ответ2xx, как только подпись и запрос будут приняты. Тело ответа может быть пустым.
2xx, может привести к повторной отправке события со стороны YCloud, поэтому выполняйте дедупликацию по id события.
Примеры стандартных полезных нагрузок
Разверните событие, чтобы просмотреть полный пример полезной нагрузки. Эти примеры взяты из спецификации OpenAPI для webhook. См. все примеры полезной нагрузки webhook для каждого поддерживаемого типа событий.Событие изменения атрибутов контакта
Событие изменения атрибутов контакта
Пример полезной нагрузки при изменении атрибутов контакта
Событие создания контакта
Событие создания контакта
Пример полезной нагрузки при создании нового контакта
Событие удаления контакта
Событие удаления контакта
Пример полезной нагрузки при удалении контакта
Событие отмены подписки клиентом
Событие отмены подписки клиентом
Пример полезной нагрузки при отмене подписки клиентом
Возобновление подписки клиентом
Возобновление подписки клиентом
Пример полезной нагрузки при возобновлении подписки клиентом
Событие архивации шаблона WhatsApp
Событие архивации шаблона WhatsApp
Пример полезной нагрузки при архивации шаблона WhatsApp
Событие разархивации шаблона WhatsApp
Событие разархивации шаблона WhatsApp
Пример полезной нагрузки при разархивации шаблона WhatsApp. Статус шаблона представляет собой текущий статус, возвращаемый Meta, и не означает новую проверку на одобрение.
Событие соединения вызова WhatsApp
Событие соединения вызова WhatsApp
Пример полезной нагрузки при установлении соединения вызова WhatsApp
Событие завершения вызова WhatsApp
Событие завершения вызова WhatsApp
Пример полезной нагрузки при завершении вызова WhatsApp
Событие обновления статуса вызова WhatsApp
Событие обновления статуса вызова WhatsApp
Пример полезной нагрузки при обновлении статуса вызова WhatsApp
Ротация секрета эндпоинта
Выполняйте ротацию секрета в случае его компрометации или в соответствии с политикой безопасности:Эндпоинт, который систематически не может принимать уведомления, может перейти в статус
pending и прекратить получение событий. Отслеживайте ошибки webhook и статус эндпоинта.
