Вебхук (Webhook)

Webhook (Вебхук) — что это

Вебхук (Webhook) — это архитектурный подход (паттерн) интеграции веб-сервисов, при котором одно приложение автоматически отправляет HTTP-запрос другому приложению при наступлении определенного события. Вебхук также называют HTTP-колбэк. Колбэк (callback) переводится как «обратный вызов», а добавление HTTP указывает на протокол, через который этот вызов происходит. В документации зарубежных сервисов также встречается вариант web callback.

Вебхук: что это

В программировании хук (hook, крючок) — это механизм, который позволяет перехватывать или встраивать свой код в выполнение программы в определенных точках. Вебхук — это частный случай хука, который работает через веб (HTTP). Существуют также другие виды хуков: системные хуки в операционных системах, хуки в базах данных, хуки в Git (pre-commit, post-commit) и многие другие. Все они объединяет общий принцип: возможность выполнить пользовательский код или вызвать внешнюю систему при наступлении определенного события.

Краткое содержание статьи:

Как работает вебхук?

Принцип работы вебхука строится на трех компонентах: событие, запрос и обработка.

Событие — это действие или факт, который произошел в системе-отправителе и служит триггером для запуска вебхука. Событие является причиной, по которой вебхук вообще отправляется. Это может быть действие пользователя (нажал кнопку, заполнил форму, оплатил заказ), автоматический процесс (завершилась сборка кода, пришло время отправки расписания) или изменение состояния системы (статус заказа изменился с «новый» на «в обработке»).

Триггер (от английского trigger — спусковой крючок) — это условие или действие, которое инициирует отправку вебхука. Например, в настройках GitHub можно выбрать триггеры: push, pull request, issue.

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

Обработка — это действия, которые выполняет система-получатель после получения запроса вебхука. Это реакция на событие и конечная цель интеграции. Обработка должна быть быстрой. Сервисы-отправители ждут ответ 5–30 секунд. Для длительных операций следует принять запрос, вернуть 200 OK, а обработку выполнить асинхронно (в фоне, через очередь).

Этапы обработки:

  1. Валидация. Проверка подлинности запроса (подпись X-Hub-Signature), структуры данных и наличия обязательных полей.
  2. Основная обработка. Выполнение бизнес-логики: сохранение в базу, отправка уведомления, создание объекта в CRM, запуск процесса, ответ отправителю.
  3. Возврат HTTP-статуса. Успех — 200 OK, ошибка — 4xx или 5xx. При ошибке отправитель может повторить запрос.

Структура запроса вебхука

Структура запроса вебхука включает несколько обязательных элементов:

  • Метод HTTP. Чаще всего используется POST, реже PUT или PATCH. Метод указывает на тип действия, которое ожидает получатель.
  • Эндпоинт (endpoint) — публичный HTTP-адрес (URL), на который направляется запрос.
  • Заголовки (headers). Служебная информация, которая сопровождает запрос. Обязательные заголовки включают Content-Type (тип содержимого, обычно application/json), User-Agent (идентификация отправителя), а также могут включать X-Hub-Signature (подпись для проверки подлинности) и X-Event-Id (идентификатор события).
  • Тело запроса (body). Данные о событии в формате JSON (чаще всего), XML или form-data. Тело включает информацию о том, что произошло, когда произошло и какие объекты затронуты.
  • Таймстемп (timestamp, временная метка) — это уникальный идентификатор момента времени, который фиксирует, когда произошло определенное событие или действие. Позволяет проверять актуальность данных и отклонять устаревшие запросы.
  • Идентификатор события (ID). Уникальный идентификатор, который позволяет отслеживать конкретное событие и предотвращать дублирование обработки при повторных попытках отправки.
  • Подпись (signature). При использовании секретного ключа отправитель вычисляет хеш от тела запроса и добавляет его в заголовок. Получатель сверяет эту подпись, чтобы убедиться, что запрос пришел от легитимного источника.

Пример — вебхук в GitHub

Когда разработчик настраивает вебхук в GitHub, он выбирает, на какие именно события реагировать: push (коммит), pull_request (запрос на слияние), issues (создание или изменение задачи). Пример запроса, который GitHub отправляет на настроенный эндпоинт при событии push (новый коммит):

POST /webhook HTTP/1.1
Host: ваш-сервер.ru
User-Agent: GitHub-Hookshot/422a781
Content-Type: application/json
X-GitHub-Event: push
X-GitHub-Delivery: 72d3162e-cc78-11e3-81ab-4c9367dc0958
X-Hub-Signature-256: sha256=7d38f2c2862c874fc92e7710fd1ba9a7f4b5e2a1c3d4e5f6a7b8c9d0e1f2a3b4

Таблица: расшифровка заголовков GitHub

Заголовок Значение Описание
X-GitHub-Event push Тип события, которое произошло
X-GitHub-Delivery 72d3162e-cc78-11e3-81ab-4c9367dc0958 Уникальный идентификатор доставки
X-Hub-Signature-256 sha256=... Подпись запроса для проверки подлинности
X-GitHub-Hook-ID 123456789 Идентификатор веб-хука, который был вызван

После обработки сервер-получатель должен вернуть HTTP-статус 200 OK. Если сервер возвращает ошибку, GitHub повторно отправит запрос несколько раз с увеличивающимися интервалами.

Входящие и исходящие вебхуки — в чем разница?

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

Исходящий вебхук (outgoing webhook) — сервис уведомляет внешние системы о своих событиях. Пример: CRM отправляет вебхук в Telegram при создании сделки.

Входящий вебхук (incoming webhook) — сервис предоставляет URL для приема данных от внешних систем. Пример: в Telegram-боте настроен URL, на который Telegram отправляет сообщения от пользователей.

Один сервис может одновременно использовать входящие и исходящие вебхуки.

Для чего нужны вебхуки?

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

Основные задачи, которые решают вебхуки:

  • Оповещение в реальном времени. Как только происходит событие, все заинтересованные системы узнают об этом немедленно. Например, при оплате заказа интернет-магазин мгновенно получает подтверждение от платежной системы.
  • Автоматизация рабочих процессов. Вебхуки соединяют разные сервисы без участия человека. Новый заказ в CRM автоматически создает задачу в Task-трекере и отправляет уведомление в Telegram.
  • Снижение нагрузки на сервер. Поскольку запросы происходят только по факту событий, сервер не тратит вычислительные мощности на обработку пустых опросов.
  • Гибкие интеграции. Разработчики могут настроить реакцию на сотни различных событий — от загрузки файла до пуш-коммита в репозиторий.

Чем отличаются Webhook и API?

Webhook — это технологический паттерн интеграции, при котором сервер-отправитель самостоятельно инициирует HTTP-запрос к серверу-получателю при наступлении определенного события. Работает по принципу Push (сервер «проталкивает» данные клиенту).

API (Application Programming Interface)— это набор правил, протоколов и методов, с помощью которых одна программа может взаимодействовать с другой. В контексте веб-интеграций REST API работает по принципу «запрос-ответ» (Pull), где клиент сам инициирует обращение к серверу.

Главное различие между вебхуком и API — в инициаторе взаимодействия.

API (особенно REST API) работает по принципу «запрос-ответ». Клиент активно запрашивает данные у сервера. Сервер пассивен — он только отвечает, когда его спрашивают. Этот подход называется Pull-моделью или Polling (опрос). API (Polling) и Pull — это синонимы, описывающие один и тот же принцип взаимодействия между программами.

Webhook работает по принципу «событие-уведомление». Сервер сам отправляет данные клиенту, когда происходит событие. Клиент пассивен — он только ждет и обрабатывает входящие уведомления. Это Push-модель. В реальных проектах эти подходы часто комбинируют.

Чем отличается: API (Polling) vs Webhook (Push)

Критерий API (Polling) Webhook (Push)
Инициатор взаимодействия Клиент (клиент сам запрашивает данные) Сервер (сервер отправляет данные при событии)
Когда происходит передача данных По расписанию или по запросу клиента Только при наступлении события
Нагрузка на сервер-источник Высокая — сервер обрабатывает множество запросов, большинство из которых пустые Низкая — запросы отправляются только когда действительно есть данные
Нагрузка на клиента Низкая — клиент просто ждет и периодически отправляет запросы Выше — клиент должен иметь публичный URL и быть готовым принимать входящие запросы
Скорость получения данных С задержкой — зависит от частоты опроса Мгновенно — данные доставляются сразу после события
Требования к клиенту Публичный URL не требуется Требуется публичный URL (эндпоинт) для приема запросов
Сложность реализации Ниже — достаточно стандартного REST API Выше — нужно настроить эндпоинт и обеспечить безопасность
Потеря данных при сбое Низкий риск — клиент повторит запрос на следующем цикле опроса Выше риск — если сервер получателя недоступен, уведомление может не дойти
Масштабируемость Сложнее — при росте числа клиентов нагрузка растет линейно Проще — нагрузка распределяется по факту событий
Подходит для Получение данных по требованию, CRUD-операции, работа с большими объемами данных, аналитика Реальное время, уведомления, автоматизация, интеграция между сервисами

Где используются вебхуки: популярные сценарии

  • Discord Webhook. Любой сервис может отправлять в Discord сообщения: уведомления о стримах, оповещения из GitHub, алерты мониторинга.
  • Telegram Webhook. Режим вебхуков для ботов: Telegram сам отправляет POST-запросы с новыми сообщениями на URL бота.
  • GitHub Webhook. При пуше, создании pull request или релиза GitHub отправляет HTTP-запрос, запуская сборку в Jenkins или деплой.
  • n8n. Платформа автоматизации позволяет создавать сценарии, запускаемые по вебхуку, и передавать данные в Google Sheets, Telegram, CRM.
  • Корпоративные системы (1С, Битрикс24, ELMA365). CRM активно использует вебхуки для интеграции с внешними системами. Можно настроить исходящие вебхуки на события: добавление лида, изменение сделки, создание задачи. Это позволяет синхронизировать CRM с 1С, сайтами, Telegram-ботами и другими сервисами.

URL вебхука — что это и где его взять?

URL вебхука (адрес вебхука, endpoint) — это публичный HTTP-адрес, на который сервис-отправитель направляет POST-запросы.

Как выглядит URL вебхука

https://ваш-сервис.ru/webhook/payment
https://api.telegram.org/bot{TOKEN}/webhook
https://discord.com/api/webhooks/123456/abcdef

Где взять URL для приема вебхуков

  • Создайте в своем приложении маршрут (роут), принимающий POST-запросы
  • Опубликуйте приложение в интернете (публичный IP или домен)
  • Для разработки используйте сервисы-туннели (ngrok, localtunnel), создающие временный публичный URL на ваш локальный компьютер

Как создать и настроить вебхук? (на примере Discord)

Шаг 1. Создайте вебхук в Discord

  • Откройте Discord, перейдите в нужный сервер
  • Выберите текстовый канал, нажмите на шестеренку (настройки канала)
  • Выберите «Интеграции» → «Создать вебхук»
  • Задайте имя, нажмите «Сохранить», скопируйте URL вебхука

Шаг 2. Настройте отправку в сервисе-источнике (GitHub)

  • В GitHub перейдите в настройки репозитория → Webhooks → Add webhook
  • Вставьте скопированный URL Discord
  • Выберите события (push, pull request, issues)
  • Сохраните

Шаг 3. Протестируйте

Сделайте коммит в GitHub. Если все настроено правильно, в Discord канале появится сообщение от вебхука.

Как отправить вебхук и проверить его работу?

Отправка через curl

curl -X POST https://discord.com/api/webhooks/123456/токен \
-H "Content-Type: application/json" \
-d '{"content": "Тестовое сообщение"}'

Отправка через интерфейс сервиса. GitHub, GitLab, Битрикс24 имеют кнопку «Test» для отправки тестового уведомления.

Отправка через Postman. HTTP-клиент позволяет вручную сформировать POST-запрос с нужными заголовками и телом.

Проверка через панель мониторинга. В GitHub, Stripe, Twilio есть история доставки вебхуков с кодами ответов.

Проверка через логи. Просмотр логов веб-сервера или приложения-получателя.

Сервисы для тестирования вебхуков

  • webhook.site — уникальный URL, показывает все входящие запросы в реальном времени
  • RequestBin — временный URL для сбора и просмотра HTTP-запросов
  • ngrok — туннель к локальному серверу с отображением запросов в веб-интерфейсе
  • smee.io — от GitHub, перенаправляет запросы на локальный сервер

Если вебхук не срабатывает, что проверить

  • Доступен ли URL получателя из интернета (не localhost)
  • Правильный ли метод HTTP (обычно POST)
  • Корректный ли Content-Type (обычно application/json)
  • Соответствует ли структура данных ожидаемой
  • Совпадает ли секретный ключ для подписи
  • Нет ли ошибок в логах (коды 400, 401, 403, 500)
  • Укладывается ли обработка в таймаут (5–30 секунд)
  • Активен ли вебхук (не отключен, не удален)

Безопасность вебхуков: секреты и подписи

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

Секретный ключ (Secret). Уникальная строка, которую задает получатель и передает отправителю. Используется для подписи запросов.

Подпись запроса (Request Signature). Отправитель вычисляет хеш (HMAC-SHA256) от тела запроса с использованием секретного ключа и добавляет в заголовок (X-Hub-Signature). Получатель вычисляет хеш самостоятельно и сверяет.

Проверка IP-адресов (IP Allowlisting). Ограничение доступа к эндпоинту по IP-адресам отправителя. Многие сервисы публикуют списки своих IP.

Дополнительные меры:

  • HTTPS. Шифрует трафик. Большинство сервисов не отправляют вебхуки на HTTP.
  • Таймстемп (Timestamp). Проверка, что запрос не слишком старый (защита от replay attacks).
  • Логирование. Журнал входящих запросов для отслеживания подозрительной активности.

Интеграция через вебхуки: как работает, преимущества и ограничения

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

В интеграции участвуют две стороны:

  • Источник событий — генерирует уведомления (новый заказ, коммит, сообщение)
  • Получатель — предоставляет публичный URL (эндпоинт) и выполняет действия (сохраняет данные, отправляет уведомление, запускает процесс)

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

Преимущества:

  • Простота. Достаточно скопировать URL из одного сервиса и вставить в другой.
  • Скорость. Уведомления доставляются мгновенно.
  • Надежность. Стандартный HTTP, большинство сервисов повторяют отправку при сбоях.
  • Масштабируемость. Нагрузка только при событиях.

Ограничения:

  • Публичный URL. Получатель должен быть доступен из интернета. Для разработки — туннели (ngrok).
  • Нет 100% гарантии доставки. При недоступности получателя уведомление может не дойти.
  • Таймауты. Обычно 10–30 секунд. Для длительных операций — асинхронная обработка (принять, вернуть 200, обработать в фоне).

ELMA365

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

Чем вебхук отличается от API?

Вебхук и API решают разные задачи. API работает по принципу «запрос-ответ»: клиент сам инициирует обращение к серверу, чтобы получить или отправить данные. При этом клиенту приходится постоянно опрашивать сервер, даже если новых данных нет. Вебхук работает по событийной модели: сервер сам отправляет данные на указанный URL, когда происходит событие. Это исключает пустые запросы и экономит ресурсы.

Как проверить, что вебхук работает?

Самый простой способ — воспользоваться сервисами-отладчиками, такими как webhook.site или RequestBin. Они генерируют уникальный URL, на который можно отправить тестовый вебхук, и показывают все входящие запросы в реальном времени. Также можно отправить тестовый запрос через curl или выполнить действие-триггер в сервисе-источнике (коммит в GitHub, создание лида в Битрикс24) и проверить, пришло ли уведомление.

Что делать, если вебхук не приходит?

Проверьте доступность URL из интернета (не localhost), корректность метода HTTP (обычно POST) и Content-Type (application/json). Убедитесь, что сервер возвращает 200 OK и укладывается в таймаут 10–30 секунд. Используйте webhook.site для отладки или панель мониторинга вебхуков в сервисе-отправителе (GitHub, Stripe), где видна история отправок и коды ответов.

Как обеспечить безопасность вебхука?

Используйте HTTPS для шифрования трафика. Настройте секретный ключ (Secret) и проверку подписи запроса (X-Hub-Signature), чтобы убедиться, что запрос пришел от легитимного отправителя. Ограничьте доступ по IP-адресам, если сервис-отправитель публикует свои диапазоны. Ведите журнал входящих запросов для обнаружения подозрительной активности.

Какие ограничения есть у вебхуков?

Нет 100% гарантии доставки — при недоступности получателя уведомление может не дойти. Сервисы ограничивают размер сообщения (обычно 4–10 MB) и количество отправок в секунду. Вебхуки работают только для событий, предусмотренных разработчиками внешней системы. Для передачи больших объемов данных (отчет за месяц) лучше использовать API.

Чем вебхук отличается от WebSocket?

WebSocket устанавливает постоянное двустороннее соединение между клиентом и сервером. Вебхук — это разовый HTTP-запрос. WebSocket подходит для чатов и игр (постоянный обмен), вебхук — для уведомлений о событиях.

Можно ли отправить вебхук без своего сервера?

Да, используя платформы автоматизации — n8n, Zapier, Make. Они предоставляют готовые URL для приема вебхуков и позволяют настроить дальнейшие действия без программирования.

Как удалить вебхук?

В большинстве сервисов это делается в том же разделе, где он создавался. Для Telegram нужно отправить запрос setWebhook с пустым URL.

Сколько вебхуков можно создать?

Ограничения зависят от сервиса. Discord позволяет 10 на канал, GitHub — 20 на репозиторий, Telegram — один на бота.

Вам может быть интересно: