Вебхуки простыми словами: как сервисы передают данные друг другу

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

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

Вебхук и опрос

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

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

Пример из документации Telegram

Telegram-бот может получать обновления двумя способами, и они взаимоисключающие: опросом через метод getUpdates или через вебхук, заданный методом setWebhook (документация Bot API). В режиме вебхука Telegram отправляет на ваш адрес HTTPS-запрос с данными о событии в формате JSON. Если ваш сервер ответил ошибкой, Telegram повторяет запрос и через разумное число попыток прекращает. А чтобы вы могли убедиться, что запрос пришёл именно от Telegram, можно задать секретный токен — он приходит в специальном заголовке каждого запроса.

В этом примере есть всё, что важно для любого вебхука: адрес, формат данных, повторы при ошибке и проверка подлинности.

Как выглядит событие

Учебный пример уведомления об оплате — поля условные, у каждого сервиса свой формат:

POST https://example.com/webhooks/payments
Content-Type: application/json

{
  "event": "payment.succeeded",
  "event_id": "evt_1042_01",
  "order_id": "1042",
  "amount": 25980,
  "currency": "KZT",
  "created_at": "2026-10-23T10:02:11Z"
}

Сайт получает такой запрос, проверяет, что он настоящий, находит заказ 1042 и меняет его статус на «оплачен».

Что может пойти не так

Ваш адрес недоступен. Сервер перегружен или обновляется. Многие сервисы повторяют отправку, но не бесконечно — как Telegram в примере выше. Поэтому важно, чтобы адрес отвечал быстро и стабильно.

Одно событие приходит дважды. Из-за повторов это нормально. Обработчик должен узнавать событие по его идентификатору и не выполнять действие повторно — иначе заказ «оплатится» два раза.

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

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

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

Что спросить у подрядчика

1. Какие события мы получаем и что делаем с каждым?
2. Как проверяется, что запрос пришёл от настоящего сервиса?
3. Что происходит, если наш сервер был недоступен?
4. Как обрабатываются повторные события?
5. Где журнал полученных событий и сколько он хранится?
6. Как вручную повторить обработку события, если что-то пошло не так?

Если на эти вопросы есть ясные ответы, интеграция, скорее всего, продумана. Если ответ «оно просто работает» — стоит уточнить.

Интеграции между сайтом, CRM, оплатой и мессенджерами входят в направление услуг PIP. Нужно связать ваши сервисы? Расскажите о задаче — разберём, какие события и куда должны передаваться.

Короткие подсказки о сайтах и автоматизации — в Telegram-канале @pip_kz.