Что такое вебхук — и почему он работает по принципу «не звони мне, я позвоню»

Представь, что ты ждёшь курьера. Можно каждые две минуты выбегать к двери и проверять — пришёл или нет. А можно просто оставить звонок: придёт — позвонит сам. Вебхук — это звонок. И когда ты строишь что-то живое (бота, автоматизацию, агента), он экономит кучу сил.

Что это такое

Вебхук (webhook) — это обратный вызов: один сервер сам отправляет сообщение другому, как только происходит событие. Не «ты спрашиваешь — он отвечает», а «случилось — он сам тебе постучал».

Классический пример. Кто-то оплатил твой товар. Платёжный сервис не ждёт, пока ты у него спросишь — он сам шлёт на твой адрес пакет: «оплата прошла, заказ №42, сумма такая-то». Твоё приложение ловит это и сразу выдаёт доступ. Мгновенно, без опросов.

Чем вебхук отличается от обычного запроса

Обычно работает наоборот — это называется polling (опрос): твоя программа дёргает чужой сервер снова и снова — «есть новое? есть новое?». Минусы очевидны:

• Задержка. Спрашиваешь раз в минуту — узнаешь о событии с опозданием до минуты.
• Трата ресурсов. 99% запросов вернут «ничего нового» — а нагрузка идёт.

Вебхук переворачивает направление. Сервер-источник сам инициирует связь:

| | Polling (опрос) | Webhook (вебхук) | |---|---|---| | Кто звонит | ты сервер | сервер тебе | | Когда узнаёшь | при следующем опросе | сразу | | Нагрузка | постоянная | только по событию |

Как это работает по шагам

1. Ты даёшь сервису свой адрес. Это URL твоего приложения, куда слать уведомления — например https://мой-сайт.ру/hook.
2. Случается событие. Оплата, новое сообщение, пуш в репозиторий — что ты подписал.
3. Сервис шлёт на твой URL пакет данных (обычно JSON) с описанием, что произошло.
4. Твой код принимает и реагирует. Выдаёт доступ, пишет в чат, запускает агента.

То есть вебхук — это просто заранее оставленный адрес, на который тебе постучатся в нужный момент.

Почему это важно тебе

Как только ты выходишь за рамки «спросил у модели — получил ответ» и строишь что-то событийное, вебхуки везде. Бот, который реагирует на сообщение; автоматизация, которая срабатывает на оплату; агент, который просыпается на новое письмо — всё это вебхуки. Собрал телеграм-бота? Telegram доставляет тебе сообщения именно вебхуком.

И тут же главная засада: твой адрес для вебхуков открыт миру. Любой, кто его знает, может прислать фейковый пакет «оплата прошла». Поэтому нормальные сервисы подписывают каждый вызов секретным ключом — а ты обязан эту подпись проверять. Без проверки вебхук = открытая дверь.

А вебхук и API — это одно и то же?

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

Нужен ли мне сервер, чтобы принимать вебхуки?

Да — нужен адрес, который доступен из интернета и работает постоянно. Локальный компьютер не подойдёт: сервису некуда стучаться. Поэтому вебхуки обычно вешают на хостинг или serverless-функцию — кусочек кода, который живёт в облаке и просыпается на каждый вызов.