Более подробное руководство по интеграции можно найти в документации для разработчиков: Developer Documentation — Webhook Integration Guide
Что такое Webhook
Webhook — это механизм обратного вызова HTTP, управляемый событиями. Когда в системе YCloud происходит определенное событие, она автоматически отправляет данные события через HTTPS-запрос на предварительно настроенный URL (адрес вебхука), устраняя необходимость регулярного опроса интерфейса.Создание Webhook
1. Добавьте эндпоинт Webhook.
Войдите в панель управления YCloud, перейдите в раздел Developer > Webhooks и нажмите Add Endpoints, чтобы создать эндпоинт вебхука.
Enter your HTTPS endpoint URL, add an optional description, and choose the events before confirming.
2. Введите адрес эндпоинта для отслеживания нужных событий.
YCloud предлагает различные варианты событий для WhatsApp, SMS, контактов, электронной почты и других сервисов.Все полезные нагрузки (payload) для событий можно найти здесь: Webhook Payload
Use Search event to find the subscriptions your endpoint needs.
3. Проверьте подпись вебхука
Всегда проверяйте подпись, чтобы убедиться, что запрос отправлен сервисом YCloud и не был подделан.
secret, чтобы проверить заголовок YCloud-Signature. Храните секрет на своем сервере в безопасном месте. Сведения о секрете эндпоинта и процессе проверки см. в Webhook Integration Guide.
Формат подписи:
Алгоритм проверки:
- Извлеките метку времени (t) и подпись (s) из заголовка запроса (метка времени представляет собой временную метку Unix в секундах).
-
Сформируйте подписываемые данные (signed payload): signed_payload:
{timestamp}.{request_body}. -
Вычислите подпись с помощью алгоритма HMAC-SHA256:
- Сравните вычисленную подпись с полученной.
4. Ответьте на Webhook
- Возвращайте код состояния 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 в аккаунте отправляться на все эти URL?
Да. Эндпоинты вебхуков, настроенные в разделе Developers > Webhooks , действуют глобально для всего аккаунта YCloud. Когда событие из любого WABA в аккаунте соответствует настроенным подпискам на события, YCloud отправляет его на каждый применимый URL вебхука. Если вам необходимо направлять разные WABA на разные URL вебхуков, используйте пользовательские приложения (custom apps). Пользовательское приложение позволяет назначать определенные телефонные номера WhatsApp и настраивать для него выделенный эндпоинт вебхука и подписки на события.Что произойдет, если все семь попыток отправки вебхука завершатся неудачно?
Если ваш сервис не восстановит работу после седьмой попытки, YCloud автоматически прекратит повторные попытки для этого события. После прекращения повторных попыток ваша система не получит данное событие автоматически. После восстановления работы вашего сервиса обратитесь в службу поддержки YCloud, чтобы запросить повторную отправку Webhook (replay). Возможность повторной отправки ограничена: YCloud может повторно отправить только те события, которые остаются доступными в системе, а более старые исторические события могут быть недоступны для повтора.Обработка ошибок
Механизм повторных попыток:
Если ваш сервис возвращает код статуса, отличный от 2xx, или не отвечает, YCloud автоматически выполнит повторную попытку:- График повторных попыток: 10 секунд → 30 секунд → 5 минут → 30 минут → 1 час → 2 часа → 2 часа.
- Максимальное количество повторных попыток: 7 раз.
- После 7 неудачных попыток: повторные попытки для этого события прекращаются.
Приостановка URL:
Для защиты системных ресурсов URL, на которых часто возникают сбои, будут временно приостановлены:- Условия срабатывания: 200 сбоев в минуту или совокупное время сбоев, превышающее 10 минут в минуту
- Длительность приостановки: 3 минуты
- Во время приостановки: запросы Webhook отправляться не будут
- После приостановки: автоматическое восстановление