Более подробные инструкции по интеграции можно найти в документации для разработчиков: Документация для разработчиков — Webhook Integration Guide
Что такое вебхук
Вебхук — это событийно-ориентированный механизм обратного вызова по HTTP. Когда в системе YCloud происходит определенное событие, она сама отправляет данные о событии через HTTPS-запрос на предварительно настроенный URL (адрес вебхука), что устраняет необходимость в постоянном опросе API.Создание вебхука
1. Добавьте эндпоинт вебхука.
Войдите в панель управления YCloud, перейдите в раздел Developer > Webhooks и нажмите Add Endpoints, чтобы создать эндпоинт вебхука.
Enter your HTTPS endpoint URL, add an optional description, and choose the events before confirming.
2. Введите адрес эндпоинта для отслеживания нужных событий.
YCloud предлагает различные варианты событий для WhatsApp, SMS, контактов, эл. почты и других сервисов.Все полезные нагрузки (payloads) для событий можно найти здесь: Webhook Payload
Use Search event to find the subscriptions your endpoint needs.
3. Проверьте подпись вебхука
Всегда проверяйте подпись, чтобы убедиться, что запрос отправлен сервисом YCloud и не был изменен.
secret для проверки заголовка YCloud-Signature. Храните этот секретный ключ в безопасном месте на своем сервере. Секретный ключ эндпоинта и процесс проверки описаны в руководстве Webhook Integration Guide.
Формат подписи:
Алгоритм проверки:
- Извлеките метку времени (t) и подпись (s) из заголовка запроса (метка времени представляет собой Unix timestamp в секундах).
-
Сформируйте подписываемую строку как
{timestamp}.{request_body}, используя точное необработанное тело запроса (raw body). Не добавляйте точку после тела запроса. -
Вычислите подпись с помощью алгоритма HMAC-SHA256:
- Сравните вычисленную подпись с полученной подписью.
4. Ответ на вебхук
- Возвращайте код состояния 2xx (например, 200, 201, 204)
- Любой ответ, отличный от 2xx, приведет к повторной отправке запроса.
- Быстрый ответ (рекомендуется в течение 6 секунд)
- Быстрые ответы повышают приоритет вашего вебхука.
- Медленные ответы (>10 секунд) могут привести к снижению приоритета.
- Асинхронная обработка (рекомендуется)
- Сразу же возвращайте ответ 200 OK.
- Обрабатывайте события в фоновых задачах или очередях.
Разрешение IP-адресов доставки вебхуков YCloud
YCloud отправляет запросы вебхуков со следующих IP-адресов серверов:8.219.65.7747.236.160.49
Добавление IP в список разрешенных — это дополнительная мера сетевой безопасности. Не забывайте проверять заголовок
YCloud-Signature для каждого запроса вебхука.Проверка журналов доставки вебхуков
YCloud регистрирует попытки доставки вебхуков, чтобы вы могли убедиться в отправке события и диагностировать ошибки доставки. Если ваша система не получает ожидаемый вебхук, перед обращением в службу поддержки проверьте журналы доставки:- В панели управления YCloud перейдите в раздел Developers > Webhooks.
-
Откройте соответствующий эндпоинт вебхука и просмотрите его журналы доставки.
- Используйте один или несколько фильтров, чтобы найти нужную попытку доставки:
- Status: отображение успешных или неудачных доставок.
- Event: фильтрация по типу события вебхука.
- Event ID: поиск по конкретному идентификатору события YCloud.
- Data ID: для событий сообщений введите идентификатор сообщения, чтобы найти запись о его доставке.
- Выберите запись, чтобы просмотреть время доставки, полезную нагрузку запроса, тело ответа и код состояния HTTP.
Часто задаваемые вопросы
Если настроить несколько URL вебхуков, будут ли события от всех WABA в аккаунте отправляться на каждый из них?
Да. Эндпоинты вебхуков, настроенные в разделе Developers > Webhooks , действуют глобально для всего аккаунта YCloud. Когда событие от любого WABA в аккаунте соответствует настроенным подпискам на события, YCloud отправляет его на каждый подходящий URL вебхука. Если вам необходимо направлять данные от разных WABA на разные URL вебхуков, используйте кастомные приложения. Кастомное приложение позволяет назначить определенные телефонные номера WhatsApp и настроить для этого приложения выделенный эндпоинт вебхука и подписки на события.Что произойдет, если все семь попыток отправки вебхука завершатся неудачно?
Если ваш сервис не восстановил работу после седьмой попытки, YCloud автоматически прекращает повторные попытки для этого события. После прекращения повторных попыток ваша система не получит это событие автоматически. После восстановления работы вашего сервиса обратитесь в службу поддержки YCloud, чтобы запросить повторную отправку webhook. Доступность повторной отправки ограничена: YCloud может повторно отправлять только те события, которые остаются доступными в системе, а более старые исторические события могут быть уже недоступны для повтора.Обработка ошибок
Механизм повторных попыток:
Если ваш сервис возвращает статус, отличный от 2xx, или не отвечает, YCloud автоматически повторит попытку:- Расписание повторов: 10 секунд → 30 секунд → 5 минут → 30 минут → 1 час → 2 часа → 2 часа.
- Максимальное количество повторных попыток: 7 раз.
- После 7 неудачных попыток: повторные попытки для этого события прекращаются.
Приостановка URL:
Для защиты системных ресурсов адреса URL с частыми сбоями временно приостанавливаются:- Условия срабатывания: 200 сбоев в минуту или совокупное время сбоев, превышающее 10 минут в минуту
- Длительность приостановки: 3 минуты
- Во время приостановки: запросы webhook не отправляются
- После завершения приостановки: автоматическое возобновление работы