Разбираемся, как IT-сервисы узнают о событиях без постоянных запросов к API, что происходит внутри вебхук-уведомления и как его обработать.
Что такое вебхуки
Вебхуки (webhooks) — это способ, с помощью которого один сервис сообщает другому о каком-либо событии.
В классическом вебхук-сценарии есть два участника:
- Сервис-источник, в котором происходит событие. Это может быть, например, платежная система, CRM, GitHub, GitLab или онлайн-касса.
- Сервис-получатель, которому нужно оперативно узнать об этом событии (например, сайт, приложение или внутренний сервис).
Событие (event) — это значимое изменение в системе. Например, успешно прошла оплата, изменился статус заказа, появился новый пользователь, завершился импорт файла или возникла ошибка.
То есть вместо того, чтобы ваш сервис регулярно запрашивал обновления через API, вы один раз указываете URL, на который источник будет присылать уведомление и передавать необходимые данные при наступлении события. Это и есть вебхук.
Разберем, как работают вебхуки, чем они отличаются от API-запросов и метода polling, какие данные передаются в уведомлении и что нужно учесть при обработке.
Как работают вебхуки
Цикл работы вебхуков можно описать так:
- Сервис-получатель создает в приложении специальный URL — эндпоинт. На него будут приходить уведомления.
- Этот же URL он указывает в настройках сервиса-источника. Там же настраивают подписку на события, о которых нужно уведомлять.
- В источнике происходит событие, на которое подписан получатель.
- Сервис-источник автоматически отправляет HTTP-запрос (обычно POST) на указанный URL вместе с данными о событии.
- Эндпоинт получателя получает запрос, проверяет его и сохраняет событие либо передает его в очередь.
- Затем получатель возвращает HTTP-статус — например, 200 OK при успешном приеме запроса или 400 Bad Request при некорректных данных.
При этом успешный ответ 200 OK не обязательно означает, что сервис уже выполнил всю работу. Обычно он сообщает, что уведомление принято. Дальнейшую обработку — обновление данных, отправку сообщения или запуск фоновой задачи — приложение может выполнять отдельно.
Из чего состоит вебхук-уведомление
Вебхук-уведомление — это HTTP-запрос, который источник отправляет на эндпоинт получателя. Его структура зависит от конкретного API. Но обычно уведомление содержит следующие части:
Помимо основных частей запроса, уведомление может содержать тип события, идентификатор доставки и подпись:
Пример HTTP-запроса:
POST /api/webhooks/events HTTP/1.1
Host: example.com
Content-Type: application/json
X-Event-Type: entity.status_changed
X-Event-Id: evt_8f3b2
X-Signature: sha256=...
{
"entityId": "obj_123",
"previousStatus": "PROCESSING",
"currentStatus": "COMPLETED",
"occurredAt": "2026-07-06T09:15:00Z"
}
Здесь есть следующее:
- POST /api/webhooks/events HTTP/1.1 — строка HTTP-запроса. В ней указаны метод POST, путь /api/webhooks/events и версия протокола HTTP/1.1.
- Host: example.com — доменное имя сервера, который принимает запрос. Вместе с путем он образует адрес https://example.com/api/webhooks/events.
- Content-Type: application/json — указывает, что тело запроса содержит данные в формате JSON.
- X-Event-Type, X-Event-Id и X-Signature — примеры заголовков. У конкретного провайдера они могут называться иначе или передаваться в другой части запроса.
- JSON в теле запроса содержит данные об объекте и произошедшем событии.
Как сервис-получатель реагирует на вебхук-уведомление
После получения вебхук-уведомления эндпоинт формирует HTTP-ответ. В нем получатель сообщает, смог ли он принять уведомление от источника. Самое важное в ответе — HTTP-статус:
Тело ответа не обязательно. Чаще всего сервису-источнику достаточно получить статус, чтобы понять, принято ли уведомление.
Разница между вебхуками, API, polling и вебсокетом
API описывает способ работы с функциями и данными сервиса. Polling и Webhook — способы получать изменения. WebSocket — отдельный протокол для постоянного двустороннего соединения.
- API. Сервис-получатель сам запрашивает данные, когда они ему нужны. Пример: интернет-магазин запрашивает статус заказа или список товаров, когда пользователь открыл страницу или нажал кнопку.
- Polling. Сервис-получатель запрашивает информацию через равные промежутки времени. Данные можно запрашивать как по каждой отдельной сущности источника, так и через общий журнал изменений (changelog). Пример: приложение каждые 30 секунд узнает, не изменился ли статус платежа.
- Вебхуки. Сервис-источник сам сообщает о событии. Получатель один раз указывает URL, а источник при наступлении события сразу отправляет HTTP-запрос. При этом вебхуки не заменяют API. Вебхук обычно содержит краткую информацию. Если нужно больше данных, после получения уведомления делают дополнительный API-запрос. Пример: платежный сервис мгновенно уведомляет магазин об успешной оплате.
- WebSocket. Постоянное двустороннее соединение. Обе стороны могут отправлять данные в реальном времени. Пример: чаты, онлайн-игры, биржевые котировки.
Создаем вебхук-уведомление с Webhook.site и Postman
Мы можем посмотреть, как работают вебхуки, на небольшом примере с помощью Webhook.site. Этот сервис создает уникальный URL для приема HTTP-запросов и показывает все пришедшие на него уведомления.
Мы будем отправлять вебхуки через Postman. Но вы также можете указать эндпоинт с Webhook.site для тестирования своего сервиса, который отправляет вебхуки.
- Откройте Webhook.site. Сервис сразу создаст уникальный URL для приема запросов.
- Скопируйте этот URL. Он будет выглядеть примерно так:
https://webhook.site/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
- Создайте новый запрос в Postman.
- Выберите метод POST и вставьте скопированный URL в адресную строку. В Postman он может отображаться в виде переменной {{webhookId}}.
- Во вкладке Headers добавьте заголовки:
| Key | Value |
| X-Event-Type | entity.status_changed |
| X-Event-Id | evt_8f3b2 |
| X-Signature | sha256=demo-signature |
Значение sha256=demo-signature — это только пример HMAC-подписи: она не пройдет проверку в реальном вебхук-обработчике
- Во вкладке Body выберите raw, затем справа выберите формат JSON. Postman добавит заголовок Content-Type: application/json автоматически.
- Вставьте в тело запроса:
{
"entityId": "obj_123",
"previousStatus": "PROCESSING",
"currentStatus": "COMPLETED",
"occurredAt": "2026-07-06T09:15:00Z"
}
- Нажмите Send и вернитесь на страницу Webhook.site.
- В списке появится полученный запрос. Сервис покажет метод, заголовки, тело запроса и другие технические данные.
Как принимать и обрабатывать вебхук-уведомления
Перед обработкой вебхук-уведомления нужно убедиться, что оно действительно пришло от ожидаемого сервиса.
Как проверить, что вебхук отправил нужный сервис
Вебхук-эндпоинт доступен из интернета, поэтому первым делом нужно проверить подлинность вебхука.
Один из распространенных способов — HMAC-подпись:
- У вашего сервиса и у сервиса-источника есть общий секретный ключ.
- Источник вычисляет подпись для тела запроса с помощью этого ключа и отправляет ее в заголовке.
- Вы делаете то же самое у себя и сравниваете подписи.
Если подписи не совпадают, то запрос отбрасывают.
Подпись нужно вычислять для исходного тела запроса до разбора JSON. Если сначала преобразовать JSON в объект, а затем собрать его заново, форматирование может измениться, и проверка не пройдет.
Идемпотентность и повторные доставки
Один и тот же вебхук может прийти несколько раз. Сервис-источник отправляет его повторно, если своевременно не получил ответ 200 OK или если произошел сбой. Поэтому важно обрабатывать такие повторы.
- Убедитесь, что каждое событие имеет уникальный идентификатор, например eventId.
- Перед обработкой сохраните этот идентификатор в базе данных, задав для него уникальное ограничение.
- Если событие уже обрабатывалось, верните 200 OK и не запускайте обработку повторно.
Такую обработку называют идемпотентной: повторное получение события не приводит к повторному выполнению действий.
Кроме того, события могут приходить не по порядку. Поэтому при обработке желательно проверять версию объекта или после получения вебхука запрашивать актуальное состояние через API.
