Webhook: что это такое, как работает и чем отличается от обычного API

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

Вебхуки особенно полезны при интеграции нескольких сервисов. Они уменьшают количество лишних запросов и позволяют быстрее реагировать на изменения. При этом webhook тесно связан с обычным API, но работает по другому принципу.

Что такое webhook и зачем нужны вебхуки

Webhook простыми словами

Проще всего представить разницу между API и webhook на примере уведомлений.

При обычной работе с API приложение самостоятельно обращается к другому серверу и спрашивает: "Появились новые данные?". Если ничего не изменилось, через некоторое время оно делает такой же запрос снова.

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

Например, интернет-магазину не нужно каждые несколько секунд спрашивать платёжную систему, оплатил ли пользователь заказ. Платёжный сервис может самостоятельно отправить webhook сразу после подтверждения платежа.

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

Какие задачи решают вебхуки

Webhook используется там, где системе необходимо быстро отреагировать на изменение в другом сервисе. Типичные примеры:

• платёжная система сообщает магазину об успешной оплате;
• CRM получает информацию о новой заявке с сайта;
• сервис доставки отправляет новый статус заказа;
• Git-платформа запускает сборку после загрузки нового кода;
• мессенджер передаёт боту новое сообщение;
• облачный сервис сообщает о завершении обработки файла.

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

Такой принцип используется не только в отдельных интеграциях, но и в более крупных программных системах. Подробнее о нём - в материале Почему event-driven архитектура делает системы быстрее и отзывчивее.

За счёт этого webhook особенно удобен для автоматизации. После получения события программа может самостоятельно изменить статус заказа, отправить уведомление пользователю, записать данные в базу или запустить другой процесс.

Как работает webhook

Событие, URL и HTTP-запрос

Чтобы webhook работал, принимающая система сначала создаёт специальный URL - endpoint. Именно на этот адрес другой сервис будет отправлять уведомления о событиях.

Схема выглядит просто:
событие → сервис формирует данные → отправляет HTTP-запрос → принимающая система обрабатывает его.

Например, пользователь оплачивает заказ. Платёжный сервис фиксирует успешную транзакцию и отправляет HTTP-запрос на webhook URL интернет-магазина. Получив этот запрос, магазин меняет статус заказа на "Оплачен" и может автоматически запустить дальнейшие действия.

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

Что находится внутри webhook-запроса

Сам webhook-запрос обычно содержит несколько частей. В URL указывается адрес обработчика, в HTTP-заголовках могут передаваться служебные данные, а основная информация о событии находится в теле запроса.

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

Упрощённо данные могут выглядеть так:

{ "event": "payment.success", "order_id": "A1024", "status": "paid" } 

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

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

Пример работы webhook

Представим интернет-магазин, подключённый к внешней платёжной системе.

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

Вместо того чтобы магазин постоянно проверял состояние платежа через API, платёжная система отправляет webhook:

payment.success → webhook магазина → изменение статуса заказа

Сервер магазина принимает уведомление, проверяет данные и автоматически переводит заказ в состояние "Оплачен". После этого система может отправить чек, уведомить склад и начать подготовку товара к отправке.

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

Webhook и API: в чём разница

API работает по запросу, webhook - по событию

Главное различие между webhook и обычным API заключается в том, кто инициирует обмен данными.

При работе с API приложение само отправляет запрос серверу. Например, клиент может запросить список заказов, получить профиль пользователя или узнать статус платежа. Сервер отвечает только после такого обращения.

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

Это можно представить как две модели:

• API - "спросить, произошло ли что-то";
• webhook - "получить сообщение, когда что-то произошло".

В технической документации эти подходы часто связывают с моделями pull и push. API обычно используется для pull-механизма, когда клиент самостоятельно забирает данные, а webhook - для push-механизма, когда данные отправляются получателю автоматически.

Webhook vs REST API

Webhook и REST API используют одни и те же базовые интернет-технологии - HTTP, URL, заголовки, методы запросов и форматы данных вроде JSON. Но назначение у них разное.

Например, через API магазин может запросить информацию о конкретном платеже. Через webhook платёжная система сама сообщит магазину, что этот платёж успешно завершён.

Поэтому сравнивать webhook и API как две полностью взаимоисключающие технологии не совсем правильно.

Webhook не заменяет API

На практике вебхуки и API чаще работают вместе.

API используется, когда программе нужно самостоятельно получить или изменить данные. Webhook нужен для того, чтобы быстро узнать о произошедшем событии.

Представим CRM-систему. Через API приложение может получить карточку клиента, изменить номер телефона или запросить историю заказов. Webhook при этом может уведомить внешнюю систему о том, что появился новый клиент или изменилась стадия сделки.

Иногда webhook передаёт только минимальную информацию: например, идентификатор объекта и тип события. После этого приложение обращается к API и получает полные данные.

Такая схема позволяет избежать постоянных запросов и одновременно сохранить гибкость обычного API.

Когда использовать webhook, а когда обычный API

Когда webhook удобнее

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

Типичные примеры - подтверждение оплаты, создание нового заказа, изменение статуса доставки, появление нового лида в CRM, загрузка файла или публикация нового кода в репозитории.

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

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

Когда лучше использовать API

Обычный API остаётся удобнее, если приложение должно получать данные в произвольный момент.

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

API также нужен, когда система должна:

• выполнять поиск;
• получать список объектов;
• создавать или изменять записи;
• удалять данные;
• запрашивать подробную информацию по идентификатору;
• самостоятельно выбирать момент обращения к серверу.

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

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

Webhook, polling и WebSocket

Webhook - не единственный способ получать обновления от другого сервиса. В зависимости от задачи могут использоваться polling и WebSocket.

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

Webhook не создаёт постоянного соединения. Сервис отправляет отдельный HTTP-запрос только после наступления заранее определённого события. Такой подход хорошо подходит для серверных интеграций, уведомлений и автоматизации.

WebSocket создаёт длительное двустороннее соединение между клиентом и сервером. Обе стороны могут передавать данные практически в любой момент. Эта технология подходит для чатов, онлайн-игр, торговых терминалов и других приложений, где требуется непрерывный обмен информацией в реальном времени.

Подробнее принцип постоянного соединения разобран в материале WebSocket простыми словами: как работает технология обмена данными в реальном времени.

Выбор зависит от характера данных. Если приложение само решает, когда запросить информацию, подходит API. Если нужно автоматически реагировать на отдельные события - webhook. Если требуется постоянный двусторонний поток данных - WebSocket.

Как настроить webhook и что важно учесть

Создание webhook endpoint

Для работы webhook принимающей системе нужен публично доступный URL, на который внешний сервис сможет отправлять HTTP-запросы. Такой адрес называют webhook endpoint.

Разработчик создаёт обработчик, который принимает входящие данные, проверяет их и выполняет нужное действие. После этого URL указывается в настройках сервиса-источника.

Например, endpoint может выглядеть так:
https://example.com/webhooks/payment

Когда происходит нужное событие, сервис отправляет запрос именно на этот адрес.

Важно, чтобы endpoint был доступен из интернета и поддерживал HTTPS. Для локальной разработки часто используют специальные туннели или тестовые сервисы, которые временно дают публичный адрес для компьютера разработчика.

Проверка подлинности webhook

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

Если злоумышленник узнает адрес webhook, он теоретически может попытаться отправить поддельное событие. Поэтому многие сервисы подписывают webhook-запросы с помощью секретного ключа.

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

Дополнительно могут использоваться секретные токены, проверка HTTPS-соединения и ограничения по IP-адресам, если сервис поддерживает такой механизм.

Повторная доставка и дубли событий

Webhook не гарантирует, что запрос всегда будет успешно обработан с первой попытки. Сервер может временно быть недоступен, соединение может оборваться, а обработка - занять слишком много времени.

Поэтому многие платформы используют механизм повторной доставки, или retry. Если endpoint вернул ошибку или не ответил вовремя, сервис повторяет запрос позже.

Из-за этого одно и то же событие иногда приходит несколько раз. Приложение должно уметь распознавать дубли и не выполнять одну операцию повторно.

Особенно важно это при работе с платежами. Если webhook об успешной оплате придёт дважды, система не должна дважды начислить баланс, создать два заказа или отправить товар повторно.

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

Логи и коды ответа

После получения webhook сервер должен вернуть HTTP-код ответа. Обычно успешная обработка подтверждается кодом из диапазона 200.

Если сервер отвечает ошибкой, внешний сервис может считать доставку неудачной и повторить запрос.

При этом не всегда стоит выполнять всю тяжёлую обработку прямо внутри webhook endpoint. Если операция занимает много времени, событие можно быстро проверить, сохранить в очередь задач, вернуть успешный ответ, а дальнейшую работу выполнить отдельно.

Логирование тоже имеет большое значение. Желательно сохранять время получения события, его тип, идентификатор и результат обработки. Это помогает понять, почему конкретное уведомление не было обработано или почему сервис отправил его повторно.

Правильно настроенный webhook - это не просто URL для приёма POST-запросов. Надёжная интеграция должна учитывать проверку источника, повторную доставку, дубли, ошибки и возможную временную недоступность сервера.

Заключение

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

Главное отличие webhook от обычного API заключается в направлении взаимодействия. При API клиент сам запрашивает данные, а при webhook сервис-источник отправляет уведомление после события. При этом вебхуки не заменяют API: чаще всего обе технологии используются вместе.

Если системе нужно получать данные по запросу, выполнять поиск или изменять объекты, подходит API. Если необходимо автоматически реагировать на конкретные события - webhook. А для постоянного двустороннего обмена данными в реальном времени чаще используется WebSocket.

При внедрении webhook важно учитывать не только отправку HTTP-запроса, но и безопасность, проверку подписи, повторную доставку, защиту от дублей и корректную обработку ошибок. Именно эти детали превращают простой webhook endpoint в надёжную интеграцию между сервисами.