[Документация Yandex Cloud](../index.md) > [Облачная терминология](index.md) > Сети и доставка контента > Вебхук

# Вебхук

Вебхук (Webhook) — это механизм, с помощью которого один веб-сервис автоматически отправляет HTTP-запрос вида `POST` на URL другого сервиса при возникновении определенного события. Термин был введен в 2007 году на основе термина [_hook_](https://en.wikipedia.org/wiki/Hooking), применяемого в программировании.

Вебхуки широко используются, в том числе в платежных системах, мессенджерах, аналитике и непрерывной интеграции ([CI/CD](ci-cd.md)). Например, GitHub или [SourceCraft](https://sourcecraft.dev) может отправлять вебхук на ваш сервер при пуше в репозиторий, чтобы автоматически запустить тестирование или развертывание новой версии приложения.

## Принцип работы {#how-works}

Вебхук автоматизирует процессы в веб-приложениях следующим образом:

1. Клиент указывает URL, по которому другой сервис должен будет отправлять уведомления.
1. Когда происходит определенное событие, сервис отправляет данные по указанному URL.
1. Проверяется доступность указанного URL — сервис должен получить код состояния `200 OK` или отправить данные повторно, если получил другой код.
1. Приложение клиента получает данные и действует в соответствии с заданной логикой. Например, обновляет базу данных или оповещает пользователей.

Как правило, для уведомлений выбирают формат JSON, так как он компактный и легко читается. Следующий вебхук от транспортной компании уведомляет интернет-магазин о том, что заказ был отправлен:

```json
{
    "event": "supplier.order_status", // событие
    "order_id": "12345", // идентификатор заказа
    "tracking_number": "EE1234567EE", // трек-номер заказа
    "status": "shipped", // статус заказа
    "estimated_delivery": "2025-11-30", // ожидаемая дата доставки
    "items": [ // список товаров
        {
            "name": "Наушники беспроводные", // название товара
            "quantity": 2 // количество товара
        }
    ]
}
```

## Отличие от API {#difference-from-api}

Вебхуки часто сравнивают с запросами по [API](rest-api.md), однако принцип действия вебхука скорее обратный. Разберем различия механизмов подробнее:

| | **API** | **Вебхук** |
|----------|-----|--------|
| **Направление запроса** | Клиент → Сервер | Сервер → Клиент |
| **Модель взаимодействия** | Pull — вы запрашиваете данные | Push — данные приходят автоматически |
| **Частота запросов** | Определяется пользователем | В режиме реального времени |
| **Реализация** | Вы пишете код для запросов | Вы предоставляете URL, на который сервис будет отправлять данные |
| **Пример использования** | Получение списка ВМ [Yandex Compute Cloud](https://yandex.cloud/ru-kz/services/compute/) | Платежная система уведомляет интернет-магазин об оплате заказа |

Обычно вебхуки используются совместно с API. Например, с помощью API клиент может самостоятельно отслеживать путь заказа, а с помощью вебхука магазин отправляет ему уведомление о том, что заказ прибыл в пункт выдачи.

## Безопасность {#security}

Чтобы злоумышленники не могли подменить вебхук, перехватить или повторить его, нужно аутентифицировать входящие POST-запросы, зашифровать их и проверить их временную метку. Существует минимальный набор механизмов защиты, которые помогут справиться со всеми наиболее распространенными проблемами:

1. Используйте только [HTTPS](ssl-certificate.md). Помимо базовой защиты, это также повышает надежность для поставщиков — большинство популярных сервисов откажутся работать без SSL.
1. Проверяйте подлинность входящих запросов. Например, используйте [HMAC](https://ru.wikipedia.org/wiki/HMAC) или [JSON Web Token](jwt.md).
1. Не используйте очевидные URL для получения вебхуков (вроде `my-site.ru/webhook`), иначе рискуете столкнуться со спамом. Лучше взять случайный набор символов, который невозможно угадать.
1. Проверяйте уникальный ID события. При повторном получении события с тем же идентификатором не обрабатывайте данные.
1. Обеспечьте быстрое подтверждение получения события (`200 OK`). Если сервер долго отвечает, можно потерять событие или получить лишние повторные отправки.

## Недостатки {#disadvantages}

Во многих [сценариях](#use-cases) вебхук способен избавить от большого количества ручной работы, однако инструмент имеет некоторые ограничения:

* Данные могут потеряться. Сбой на севере или проблемы на стороне клиента — и данные просто не дойдут.
* Сложная настройка безопасности. Вебхук может работать со всеми необходимыми [механизмами защиты](#security), однако для их настройки нужна высокая квалификация.
* В условиях повышенной нагрузки требуются соразмерные вычислительные мощности. Например, если у вас настроены уведомления о новых заказах, то в период распродажи не каждый сервер сможет обработать все события.
* Ограничения на события. Иногда вебхук попросту не способен отследить событие, например, если оно происходит офлайн.
* Отсутствуют механизмы упорядочивания и обработки дубликатов.
* Нет встроенной очереди и буферизации. Если не успеть обработать событие, его можно потерять.
* Плохая масштабируемость. Для каждого нового обработчика нужно создавать дубликат вебхука.

## Альтернативы {#alternatives}

Сегодня в качестве альтернативы вебхуку чаще всего используются две технологии:

* Message Queue (очередь сообщений) — механизм, который встраивается в систему как посредник, хранящий и передающий события от сервиса к клиенту. Например, [Yandex Message Queue](https://yandex.cloud/ru-kz/services/message-queue/).
* Polling (регулярный опрос API) — клиент периодически самостоятельно уточняет необходимую информацию у сервиса.

Рассмотрим различия между подходами подробнее:

| | **Webhook** | **Message Queue** | **Polling** |
|--------|---------|---------------|---------|
| **Гарантия доставки** | Ограниченные попытки передать событие | Зависит от посредника | Полная гарантия (клиент сам забирает данные) |
| **Упорядоченность событий** | Нет | Да | Да |
| **Задержка доставки** | Низкая | Очень низкая | Высокая |
| **Нагрузка на ваш сервер** | Высокая | Низкая | Зависит от частоты запросов |
| **Сложность реализации** | Средняя | Высокая | Низкая |
| **Масштабируемость** | Плохая | Отличная | Хорошая, но дорогая |
| **Размер и частота событий** | Ограничены провайдером | Практически нет ограничений | Зависит от API |
| **Безопасность** | Настраивается вручную | Встроенная авторизация и шифрование | Обычная аутентификация API |
| **Стоимость** | Бесплатно | От низкой до очень высокой | Зависит от частоты запросов |

### Сценарии использования {#use-cases}

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

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

  * отслеживание изменений в платежных системах;
  * непрерывная интеграция с репозиториями;
  * автоматические посты в соцсетях и чат-боты;
  * оперативное получение изменений из CRM.

* **Message Queue** — оптимальный выбор для масштабируемых систем с большим количеством событий для гарантии доставки и обработки. Чаще всего используется крупными корпоративными системами. Популярные реализации:

  * обработка заказов в крупном интернет-магазине;
  * получение логов и метрик;
  * работа с событийно-ориентированной микросервисной архитектурой;
  * обработка постоянных фоновых задач.

* **Polling** — лучший выбор для случаев, когда события редкие, их можно получить с задержкой, но гарантированно. Подходит для небольших приложений, в которых простота и надежность важнее скорости. Популярные реализации:

  * обновление информации на странице по кнопке;
  * простые или старые API, которые работают только с запросами вида `GET`;
  * отслеживание статусов заявок в некоторых государственных сервисах;
  * мониторинг простых систем.

Нередко также можно встретить системы, в которых очередь сообщений работает вместе с вебхуком. Например, события с внешних сервисов отслеживаются вебхуком, а затем кладутся в очередь для асинхронной обработки.

## Вебхуки в Yandex Cloud {#webhook-yc}

В Yandex Cloud есть следующие сервисы, которые работают с вебхуками:

* [Yandex Managed Service for GitLab](https://yandex.cloud/ru-kz/services/managed-gitlab/) — сервис для управления платформой разработки GitLab в инфраструктуре Yandex Cloud. Подробнее в [документации](../managed-gitlab/index.md).
* [SourceCraft](https://sourcecraft.dev) — платформа от Яндекса для разработки IT-продуктов в режиме непрерывной интеграции. Подробнее в [документации](https://sourcecraft.dev/portal/docs/ru).
* [Yandex Cloud Functions](https://yandex.cloud/ru-kz/services/functions/) — сервис для создания и управления функциями, которые можно использовать в качестве вебхуков. Подробнее в [документации](../functions/index.md).
* [Yandex Cloud Postbox](https://yandex.cloud/ru-kz/services/postbox/) — сервис для отправки почтовых сообщений, которые можно отслеживать с помощью вебхуков. Подробнее в [документации](../tutorials/serverless/postbox-webhook.md).
* [Yandex Monitoring](https://yandex.cloud/ru-kz/services/monitoring/) — сервис для сбора метрик и отслеживания работы приложений, события из которого можно получать с помощью вебхуков. Подробнее в [документации](../monitoring/operations/alert/alert-call-function.md).
* [Yandex API Gateway](https://yandex.cloud/ru-kz/services/api-gateway/) — сервис для создания и управления API-шлюзами, которые можно использовать в качестве вебхуков. Подробнее в [документации](../serverless-integrations/tutorials/telegram-ai-bot-workflows.md).

Вы также можете настроить отслеживание событий в облачных ресурсах в Yandex Cloud с помощью вебхуков. Подробнее в [документации](../support/notify.md#webhook).