> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

<Info>
  Более подробное руководство по интеграции можно найти в документации для разработчиков: Developer Documentation — [Webhook Integration Guide](/ru/api-reference/guides/api-fundamentals/configure-webhooks)
</Info>

## Что такое Webhook

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

## Создание Webhook

### 1. Добавьте эндпоинт Webhook.

Войдите в **панель управления YCloud**, перейдите в раздел Developer > Webhooks и нажмите Add Endpoints, чтобы создать эндпоинт вебхука.

<Frame caption="Enter your HTTPS endpoint URL, add an optional description, and choose the events before confirming.">
  <img src="https://mintcdn.com/lchnan/gXEJIQXV2JH2VUQJ/product-assets/english-help-2026-09-22/developer-webhook-add-annotated.svg?fit=max&auto=format&n=gXEJIQXV2JH2VUQJ&q=85&s=6c04b793e7a8e7952e7931cd10232773" alt="Пустое диалоговое окно Add Endpoints с выделенным полем Endpoint URL." width="3024" height="1656" data-path="product-assets/english-help-2026-09-22/developer-webhook-add-annotated.svg" />
</Frame>

### 2. Введите адрес эндпоинта для отслеживания нужных событий.

YCloud предлагает различные варианты событий для WhatsApp, SMS, контактов, электронной почты и других сервисов.

<Info>
  Все полезные нагрузки (payload) для событий можно найти здесь: [Webhook Payload](/ru/api-reference/webhooks/test-webhooks)
</Info>

<Frame caption="Use Search event to find the subscriptions your endpoint needs.">
  <img src="https://mintcdn.com/lchnan/gXEJIQXV2JH2VUQJ/product-assets/english-help-2026-09-22/developer-webhook-events-annotated.svg?fit=max&auto=format&n=gXEJIQXV2JH2VUQJ&q=85&s=81cb1ab6ab3e979bb8ad6fdd9c4d4122" alt="Меню Webhook Events с названиями событий и полем Search event." width="3024" height="1656" data-path="product-assets/english-help-2026-09-22/developer-webhook-events-annotated.svg" />
</Frame>

### 3. Проверьте подпись вебхука

<Info>
  Всегда проверяйте подпись, чтобы убедиться, что запрос отправлен сервисом YCloud и не был подделан.
</Info>

Используйте секрет подписи эндпоинта `secret`, чтобы проверить заголовок `YCloud-Signature`. Храните секрет на своем сервере в безопасном месте. Сведения о секрете эндпоинта и процессе проверки см. в [Webhook Integration Guide](/ru/api-reference/guides/api-fundamentals/configure-webhooks).

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

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
YCloud-Signature: t={timestamp},s={signature}
```

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

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

   ```js theme={"theme":{"light":"github-light","dark":"github-dark"}}
   HMAC-SHA256(signed_payload, secret)
   ```
4. Сравните вычисленную подпись с полученной.

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

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

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

YCloud отправляет запросы вебхуков со следующих IP-адресов серверов:

* `8.219.65.77`
* `47.236.160.49`

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

<Note>
  Разрешение IP-адресов является дополнительной мерой сетевой защиты. Обязательно продолжайте проверять заголовок `YCloud-Signature` для каждого запроса вебхука.
</Note>

## Проверка журналов доставки вебхуков

YCloud записывает попытки доставки вебхуков, чтобы вы могли подтвердить отправку события и устранить ошибки доставки.

Если ваша система не получает ожидаемый вебхук, проверьте журналы доставки перед обращением в службу поддержки:

1. В панели управления YCloud перейдите в раздел **Developers** > **Webhooks**.

2. Откройте нужный эндпоинт вебхука и просмотрите журналы его доставки.
   <img src="https://mintcdn.com/lchnan/7AejdQWTE_GcFoQy/images/image-21.png?fit=max&auto=format&n=7AejdQWTE_GcFoQy&q=85&s=5d979a36e16efc2e224bb68dafe64d89" alt="Изображение" width="2912" height="1578" data-path="images/image-21.png" />

3. Используйте один или несколько фильтров, чтобы найти попытку доставки:

* **Status**: отображение успешных или неудачных доставок.
* **Event**: фильтрация по типу события вебхука.
* **Event ID**: поиск по конкретному идентификатору события YCloud.
* **Data ID**: для событий сообщений введите идентификатор сообщения, чтобы найти запись о его доставке.

4. Выберите запись, чтобы просмотреть время доставки, полезную нагрузку запроса, тело ответа и HTTP-код состояния.

В записи о неудачной доставке указывается причина сбоя. Используйте данные ответа и ошибки, чтобы проверить URL эндпоинта, доступность, время обработки и HTTP-ответ.

<Tip>
  Если ожидаемый вебхук отсутствует, сначала выполните поиск по идентификатору сообщения или события. Это поможет понять, произошел ли сбой доставки или событие не соответствует подпискам эндпоинта.
</Tip>

Неудачные доставки повторяются автоматически в соответствии с приведенным ниже [графиком повторных попыток](#retry-mechanism). При диагностике проверяйте последнюю попытку в журналах.

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

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

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

Если вам необходимо направлять разные WABA на разные URL вебхуков, используйте [пользовательские приложения (custom apps)](/ru/documentation/developer/create-and-configure-a-custom-app). Пользовательское приложение позволяет назначать определенные телефонные номера WhatsApp и настраивать для него выделенный эндпоинт вебхука и подписки на события.

### Что произойдет, если все семь попыток отправки вебхука завершатся неудачно?

Если ваш сервис не восстановит работу после седьмой попытки, YCloud автоматически прекратит повторные попытки для этого события. После прекращения повторных попыток ваша система не получит данное событие автоматически.

После восстановления работы вашего сервиса обратитесь в службу поддержки YCloud, чтобы запросить повторную отправку Webhook (replay). Возможность повторной отправки ограничена: YCloud может повторно отправить только те события, которые остаются доступными в системе, а более старые исторические события могут быть недоступны для повтора.

<Warning>
  Не полагайтесь на повторную отправку Webhook как на стратегию восстановления. Отслеживайте состояние вашей конечной точки, своевременно отвечайте со статусом `2xx` и как можно скорее исследуйте сбои в журналах доставки Webhook.
</Warning>

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

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

Если ваш сервис возвращает код статуса, отличный от 2xx, или не отвечает, YCloud автоматически выполнит повторную попытку:

* **График повторных попыток**: 10 секунд → 30 секунд → 5 минут → 30 минут → 1 час → 2 часа → 2 часа.
* **Максимальное количество повторных попыток**: 7 раз.
* **После 7 неудачных попыток**: повторные попытки для этого события прекращаются.

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

Для защиты системных ресурсов URL, на которых часто возникают сбои, будут временно приостановлены:

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.