Вебхук

Вебхук (Webhook) — это механизм, с помощью которого один веб-сервис автоматически отправляет HTTP-запрос вида POST на URL другого сервиса при возникновении определенного события. Термин был введен в 2007 году на основе термина hook, применяемого в программировании.

Вебхуки широко используются, в том числе в платежных системах, мессенджерах, аналитике и непрерывной интеграции (CI/CD). Например, GitHub или SourceCraft может отправлять вебхук на ваш сервер при пуше в репозиторий, чтобы автоматически запустить тестирование или развертывание новой версии приложения.

Принцип работыПринцип работы

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

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

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

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

Отличие от APIОтличие от API

Вебхуки часто сравнивают с запросами по API, однако принцип действия вебхука скорее обратный. Разберем различия механизмов подробнее:

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

БезопасностьБезопасность

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

1. Используйте только HTTPS. Помимо базовой защиты, это также повышает надежность для поставщиков — большинство популярных сервисов откажутся работать без SSL.
2. Проверяйте подлинность входящих запросов. Например, используйте HMAC или JSON Web Token.
3. Не используйте очевидные URL для получения вебхуков (вроде my-site.ru/webhook), иначе рискуете столкнуться со спамом. Лучше взять случайный набор символов, который невозможно угадать.
4. Проверяйте уникальный ID события. При повторном получении события с тем же идентификатором не обрабатывайте данные.
5. Обеспечьте быстрое подтверждение получения события (200 OK). Если сервер долго отвечает, можно потерять событие или получить лишние повторные отправки.

НедостаткиНедостатки

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

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

АльтернативыАльтернативы

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

• Message Queue (очередь сообщений) — механизм, который встраивается в систему как посредник, хранящий и передающий события от сервиса к клиенту. Например, Yandex Message Queue.
• Polling (регулярный опрос API) — клиент периодически самостоятельно уточняет необходимую информацию у сервиса.

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

Сценарии использованияСценарии использования

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

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

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

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

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

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

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

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

Вебхуки в Yandex CloudВебхуки в Yandex Cloud

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

• Yandex Managed Service for GitLab — сервис для управления платформой разработки GitLab в инфраструктуре Yandex Cloud. Подробнее см. в документации.
• SourceCraft — платформа от Яндекса для разработки IT-продуктов в режиме непрерывной интеграции. Подробнее см. в документации.
• Yandex Cloud Functions — сервис для создания и управления функциями, которые можно использовать в качестве вебхуков. Подробнее см. в документации.
• Yandex Cloud Postbox — сервис для отправки почтовых сообщений, которые можно отслеживать с помощью вебхуков. Подробнее см. в документации.
• Yandex Monitoring — сервис для сбора метрик и отслеживания работы приложений, события из которого можно получать с помощью вебхуков. Подробнее см. в документации.
• Yandex API Gateway — сервис для создания и управления API-шлюзами, которые можно использовать в качестве вебхуков. Подробнее см. в документации.

Вы также можете настроить отслеживание событий в облачных ресурсах в Yandex Cloud с помощью вебхуков. Подробнее см. в документации.