Webhook

Webhook — это механизм автоматической передачи данных между информационными системами, при котором одно приложение в реальном времени отправляет HTTP-запрос (обычно POST) на заранее заданный URL-адрес другого приложения при наступлении определённого события. В отличие от традиционного опроса (polling), когда клиент периодически запрашивает сервер о наличии новых данных, вебхук работает по принципу обратного вызова (callback): сервер сам инициирует отправку данных клиенту, что обеспечивает более высокую оперативность и снижает нагрузку на сеть.

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

Взаимодействие через вебхуки строится по модели «издатель-подписчик» (publish-subscribe). Процесс включает три основных этапа:

1. Регистрация — клиент (получатель) предоставляет издателю (источнику событий) URL-адрес своего эндпоинта, на который будут отправляться уведомления. Часто вместе с URL передаются параметры аутентификации (например, секретный токен).
2. Наступление события — в системе издателя происходит заданное событие: создание новой записи, изменение статуса заказа, загрузка файла, получение платежа и т.п.
3. Отправка уведомления — издатель формирует HTTP-запрос (как правило, POST) с телом, содержащим данные о событии в структурированном формате (JSON, XML, форма данных), и отправляет его на зарегистрированный URL. Получатель обрабатывает запрос и выполняет необходимые действия.

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

Формат данных

Тело вебхук-запроса обычно содержит информацию о типе события, идентификаторе объекта, временной метке и полезной нагрузке (payload). Наиболее распространённый формат — JSON. Пример тела запроса от платёжного шлюза:

``json { "event": "payment.completed", "data": { "id": "txn_123456", "amount": 1500.00, "currency": "RUB", "status": "completed", "timestamp": "2025-03-15T10:30:00Z" } } ``

Издатель может отправлять как минимальный набор данных (например, только идентификатор объекта), так и полную информацию о событии — это определяется соглашением сторон.

Типы вебхуков

Вебхуки классифицируются по нескольким признакам.

По способу отправки

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

По источнику события

• Серверные вебхуки — инициируются серверными приложениями (платёжные системы, CRM, облачные сервисы).
• Клиентские вебхуки — отправляются из браузера или мобильного приложения (например, при загрузке файла пользователем).

По гарантии доставки

• At most once — сообщение отправляется один раз, без подтверждения получения. При сбое данные теряются.
• At least once — сообщение отправляется повторно, если не получено подтверждение (HTTP 200 OK). Возможны дубликаты.
• Exactly once — гарантируется однократная доставка, что требует сложной логики идемпотентности.

Применение

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

Платёжные системы

Платёжные шлюзы (например, ЮKassa, Stripe) отправляют вебхуки при успешном или неудачном списании средств, возврате платежа, изменении статуса подписки. Это позволяет интернет-магазинам автоматически обновлять статус заказа без постоянного опроса API.

Системы управления контентом (CMS)

Популярные CMS (WordPress, Joomla) могут отправлять вебхуки при публикации новой статьи, добавлении комментария, регистрации пользователя. Это используется для интеграции с системами рассылок, кэширования или аналитики.

Облачные сервисы и DevOps

Сервисы непрерывной интеграции (GitHub Actions, GitLab CI/CD) отправляют вебхуки при пуше кода, создании pull request или завершении сборки. Это позволяет автоматически запускать тесты, развёртывать приложения на серверах или уведомлять команду в мессенджерах.

Интернет вещей (IoT)

Устройства IoT (датчики, умные розетки) могут отправлять вебхуки при изменении температуры, обнаружении движения или превышении пороговых значений. Данные поступают на центральный сервер для анализа и принятия решений.

Мессенджеры и социальные сети

Популярные мессенджеры (Telegram, Slack) предоставляют API вебхуков для получения уведомлений о новых сообщениях, вступлениях в группу, реакциях. Разработчики ботов регистрируют URL, на который сервер мессенджера отправляет входящие сообщения.

Проблемы и ограничения

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

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

• Секретный токен — передаётся в заголовке или теле запроса, сверяется с сохранённым значением.
• Подпись HMAC — тело запроса подписывается секретным ключом, подпись передаётся в заголовке (например, X-Hub-Signature).
• IP-белые списки — получатель принимает запросы только с известных IP-адресов издателя.

Надёжность доставки

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

• Повторные попытки — отправка с возрастающими интервалами (retry with backoff).
• Очереди сообщений — хранение неотправленных вебхуков в очереди (RabbitMQ, Amazon SQS) с последующей доставкой.
• Логирование — запись всех попыток отправки для последующего анализа.

Обработка дубликатов

При повторных отправках получатель может получить несколько одинаковых запросов. Для обеспечения идемпотентности необходимо:

• Хранить идентификаторы обработанных событий.
• Проверять уникальность идентификатора перед выполнением действия.

Отсутствие гарантии порядка

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

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

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

• Polling (опрос) — клиент периодически запрашивает сервер о новых данных. Подходит для систем, где события редки или не критична задержка.
• WebSocket — постоянное двустороннее соединение, позволяющее серверу отправлять данные клиенту в реальном времени. Используется в чатах, трейдинговых системах.
• Server-Sent Events (SSE) — односторонний канал от сервера к клиенту через HTTP. Проще WebSocket, но не поддерживает двустороннюю связь.
• Message Queue — асинхронная передача сообщений через брокер (RabbitMQ, Apache Kafka). Обеспечивает гарантированную доставку и порядок сообщений, но требует дополнительной инфраструктуры.

Примеры реализации

Настройка вебхука в GitHub

Владелец репозитория может добавить вебхук в настройках проекта (Settings → Webhooks). Указывается URL получателя, тип событий (например, push, pull_request), секретный токен. При каждом пуше GitHub отправляет POST-запрос с данными о коммитах.

Создание вебхука в Telegram

Для создания бота в Telegram используется метод setWebhook, который принимает URL сервера, на который будут отправляться обновления. Сервер должен быть доступен по HTTPS и иметь валидный SSL-сертификат.

Вебхуки в 1С-Битрикс

Система управления сайтами 1С-Битрикс поддерживает вебхуки для интеграции с внешними сервисами. При изменении товара, заказа или пользователя система отправляет уведомление на указанный URL.

Стандарты и спецификации

Несмотря на широкое распространение, единого стандарта для вебхуков не существует. Наиболее известные попытки стандартизации:

• Webhooks Subscriptions — спецификация от W3C, описывающая протокол подписки на вебхуки.
• Standard Webhooks — проект, определяющий общие правила для формата, подписи и повторных попыток.
• CloudEvents — спецификация от Cloud Native Computing Foundation (CNCF), унифицирующая формат событий для облачных систем.

Источники

1. Документация GitHub Webhooks. — GitHub Docs.
2. Telegram Bot API: setWebhook. — Telegram API Documentation.
3. Webhooks: The Definitive Guide. — Zapier Engineering Blog, 2019.
4. CloudEvents Specification. — Cloud Native Computing Foundation.
5. Standard Webhooks — Open Source Specification. — standardwebhooks.com.
6. Richardson L., Ruby S. RESTful Web APIs. — O'Reilly Media, 2013.