Перейти к основному содержанию
Более подробные инструкции по интеграции можно найти в документации для разработчиков: Developer Documentation — Webhook Integration Guide

Что такое Webhook

Webhook — это событийно-ориентированный механизм обратного вызова HTTP. Когда в системе YCloud происходит определенное событие, она упреждающе отправляет данные события через HTTPS-запрос на предварительно настроенный URL (адрес webhook), тем самым устраняя необходимость в частом опросе интерфейса.

Создание Webhook

1. Добавьте конечную точку Webhook.

Войдите в панель управления YCloud, перейдите в раздел Developer > Webhooks и нажмите Add Endpoints, чтобы создать конечную точку webhook.
Пустое диалоговое окно Add Endpoints с выделенным полем Endpoint URL.

Enter your HTTPS endpoint URL, add an optional description, and choose the events before confirming.

2. Введите адрес конечной точки для мониторинга соответствующих событий.

YCloud предлагает различные варианты событий для WhatsApp, SMS, контактов, электронной почты и многого другого.
Все полезные нагрузки (payloads) для событий можно найти здесь: Webhook Payload
Меню Webhook Events с названиями событий и полем Search event.

Use Search event to find the subscriptions your endpoint needs.

3. Проверьте подпись webhook

Всегда проверяйте подпись, чтобы убедиться, что запрос отправлен сервисом YCloud и не был изменен сторонними лицами.
Используйте секретный ключ подписи конечной точки (secret) для проверки заголовка YCloud-Signature. Храните этот секретный ключ в безопасности на своем сервере. См. раздел Webhook Integration Guide для получения информации о секрете конечной точки и процедуре проверки.

Формат подписи:

Алгоритм проверки:

  1. Извлеките метку времени (t) и подпись (s) из заголовка запроса (метка времени представляет собой метку времени Unix в секундах).
  2. Сформируйте подписываемую полезную нагрузку в виде {timestamp}.{request_body}, используя точное исходное тело запроса (raw body). Не добавляйте точку после тела запроса.
  3. Вычислите подпись с помощью алгоритма HMAC-SHA256:
  4. Сравните вычисленную подпись с полученной.

4. Ответьте на Webhook

  1. Возвращайте код состояния 2xx (например, 200, 201, 204)
    • Любой ответ, отличный от 2xx, инициирует повторную попытку.
  2. Быстрый ответ (рекомендуется в течение 6 секунд)
    • Быстрые ответы повышают приоритет вашего webhook.
    • Медленные ответы (>10 секунд) могут привести к понижению приоритета.
  3. Асинхронная обработка (рекомендуется)
    • Сразу возвращайте 200 OK.
    • Обрабатывайте события в фоновых задачах/очередях.

Разрешите IP-адреса доставки вебхуков YCloud

YCloud отправляет webhook-запросы со следующих IP-адресов серверов:
  • 8.219.65.77
  • 47.236.160.49
Если ваш корпоративный брандмауэр, шлюз или сервер webhook ограничивает входящий трафик по IP-адресу источника, добавьте оба адреса в список разрешенных. Разрешение только одного адреса может привести к блокировке части доставок webhook.
Белый список IP-адресов является дополнительной мерой сетевой защиты. Продолжайте проверять заголовок YCloud-Signature для каждого webhook-запроса.

Проверка журналов доставки webhook

YCloud фиксирует попытки доставки webhook, чтобы вы могли подтвердить отправку события и устранить ошибки доставки. Если ваша система не получает ожидаемый webhook, проверьте журналы доставки перед эскалацией проблемы:
  1. В панели управления YCloud перейдите в раздел Developers > Webhooks.
  2. Откройте соответствующую конечную точку webhook и просмотрите журналы ее доставки. Изображение
  3. Используйте один или несколько фильтров, чтобы найти попытку доставки:
  • Status: отображение успешных или неудачных доставок.
  • Event: фильтрация по типу события webhook.
  • Event ID: поиск по конкретному идентификатору события YCloud.
  • Data ID: для событий сообщений введите идентификатор сообщения, чтобы найти запись о его доставке.
  1. Выберите запись, чтобы просмотреть время доставки, полезную нагрузку запроса, тело ответа и код состояния HTTP.
Запись о сбое содержит соответствующую причину ошибки доставки. Используйте данные ответа и ошибки, чтобы проверить URL конечной точки, ее доступность, время обработки и HTTP-ответ.
Если ожидаемый webhook отсутствует, сначала выполните поиск по идентификатору сообщения или идентификатору события. Это поможет отличить сбой доставки от ситуации, когда событие не соответствует подпискам конечной точки.
Повторные попытки при неудачной доставке выполняются автоматически в соответствии с расписанием повторов, приведенным ниже. В процессе устранения неполадок проверяйте последнюю попытку в журналах.

Часто задаваемые вопросы

Если настроить несколько URL-адресов webhook, будут ли события из каждого WABA в аккаунте отправляться на них все?

Да. Конечные точки webhook, настроенные в разделе Developers > Webhooks , являются глобальными для аккаунта YCloud. Когда событие из любого WABA в аккаунте соответствует настроенным подпискам на события, YCloud отправляет его на каждый применимый URL webhook. Если вам необходимо направлять разные WABA на разные URL webhook, используйте пользовательские приложения. Пользовательское приложение позволяет назначать конкретные телефонные номера WhatsApp и настраивать для него выделенную конечную точку webhook и подписки на события.

Что произойдет, если все семь попыток отправки webhook завершатся ошибкой?

Если после седьмой повторной попытки ваш сервис так и не восстановил работу, YCloud автоматически прекращает повторные попытки для этого события. После прекращения повторов ваша система не получит данное событие автоматически. После восстановления работы вашего сервиса обратитесь в службу поддержки YCloud, чтобы запросить повторную отправку вебхуков (webhook replay). Доступность повторной отправки ограничена: YCloud может повторно отправлять только те события, которые остаются доступными в системе, а более старые исторические события могут быть уже недоступны для воспроизведения.
Не полагайтесь на повторную отправку вебхуков как на стратегию восстановления. Отслеживайте состояние вашей конечной точки, своевременно отвечайте со статусом 2xx и оперативно расследуйте сбои в журналах доставки вебхуков.

Обработка ошибок

Механизм повторных попыток:

Если ваш сервис возвращает код состояния, отличный от 2xx, или не отвечает, YCloud автоматически выполнит повторную попытку:
  • Расписание повторных попыток: 10 секунд → 30 секунд → 5 минут → 30 минут → 1 час → 2 часа → 2 часа.
  • Максимальное количество повторных попыток: 7 раз.
  • После 7 неудачных попыток: повторные попытки отправки события больше производиться не будут.

Приостановка URL:

Для защиты системных ресурсов URL с частыми сбоями временно приостанавливаются:
  • Условия срабатывания: 200 сбоев в минуту или совокупное время сбоев превышает 10 минут в минуту
  • Длительность приостановки: 3 минуты
  • Во время приостановки: запросы Webhook отправляться не будут
  • После приостановки: автоматическое восстановление