Вебхук
Вебхук (webhook) — HTTP-запрос, который одна система автоматически шлёт другой при наступлении события. В отличие от обычного API данные приходят сами, без постоянного опроса сервера. Задержка реакции обычно меньше секунды.
Определение вебхука
Вебхук (webhook) — HTTP-запрос, который одна система автоматически отправляет другой в момент наступления события. Если обычное API работает по принципу запрос-ответ и инициатор тянет данные сам, то вебхук переворачивает логику: данные приходят сами, как только что-то произошло. Поэтому вебхуки называют обратными API или callback-ами. Термин ввёл Джефф Линдсей в 2007 году. Сегодня это стандартный способ связать сервисы: платёжный шлюз сообщает об оплате, CRM узнаёт о новой заявке, мессенджер передаёт входящее сообщение.
Главное преимущество в эффективности. Вместо того чтобы каждую секунду спрашивать сервер не случилось ли чего, система ждёт, когда ей сообщат. Это экономит запросы и даёт реакцию почти в реальном времени — задержка обычно меньше секунды.
Как работает вебхук
Принимающая сторона создаёт URL-эндпоинт и регистрирует его в настройках сервиса-источника. Когда происходит событие, источник формирует HTTP-запрос методом POST с данными в теле (чаще в формате JSON) и отправляет на этот URL. Приёмник обрабатывает данные и возвращает код 200. Настройка таких связок — частая задача при внедрении CRM и ERP или разработке чат-ботов.
| Шаг | Что происходит | Кто участвует |
|---|---|---|
| 1. Регистрация | Указывают URL для уведомлений | Приёмник |
| 2. Событие | Случилось действие: оплата, заявка | Источник |
| 3. Отправка | POST-запрос с данными события | Источник |
| 4. Обработка | Приёмник разбирает payload и отвечает кодом 200 | Приёмник |
Если приёмник вернул ошибку или не ответил, надёжные сервисы повторяют отправку с нарастающей задержкой. Поэтому обработчик обязан быть идемпотентным — корректно реагировать на повторную доставку события, чтобы не создать два одинаковых заказа.
Виды и безопасность вебхуков
Вебхуки различают по типу события и по способу защиты. Поскольку эндпоинт открыт в интернет, его обязательно ограждают от подделки.
| Аспект | Решение |
|---|---|
| Подпись запроса | HMAC-подпись в заголовке, приёмник проверяет секретом |
| Секретный токен | Отдельный ключ в URL или заголовке |
| Белый список IP | Приём только с адресов сервиса-источника |
| HTTPS | Шифрование канала, защита данных в пути |
| Идемпотентность | Защита от двойной обработки повторных доставок |
Самая частая дыра — открытый эндпоинт без проверки подписи. Злоумышленник может прислать поддельное уведомление об оплате, и система засчитает несуществующий платёж. Поэтому проверка HMAC-подписи секретным ключом обязательна для любого платёжного вебхука.
Инструменты и пример
Для отладки используют сервисы вроде webhook.site и ngrok, которые показывают приходящие запросы и пробрасывают локальный сервер в интернет. Очереди вроде RabbitMQ помогают не терять события при всплесках нагрузки. Связки вебхуков лежат в основе большинства интеграций при комплексной разработке.
Мини-кейс: интернет-магазин терял заказы, потому что оператор вручную переносил оплаты из банка в CRM с задержкой в часы. Настроили вебхук от платёжного шлюза: при подтверждении оплаты POST-запрос автоматически менял статус заказа и запускал сборку. Время от оплаты до начала обработки сократилось с 3 часов до 8 секунд, ручных ошибок не стало вовсе. За первый месяц магазин обработал 2 100 заказов без единого пропущенного платежа.
Связанные концепции
- API — обычное API тянет данные по запросу, а вебхук сам присылает их при событии; на практике работают в паре.
- CRM — вебхуки автоматически наполняют CRM заявками и оплатами из сайта, чат-бота и платёжных систем.
- Чат-бот — получает входящие сообщения от мессенджера именно через вебхук.
- AI-ассистент — реагирует на события вроде новой заявки, получая их через вебхук.
- Polling — противоположный подход с регулярным опросом сервера; дороже и медленнее вебхука.
- Payload — тело запроса с данными события, обычно в формате JSON.
Частые ошибки
- Эндпоинт без проверки подписи — любой может прислать поддельное событие, например фейковую оплату.
- Нет идемпотентности — повторная доставка создаёт два одинаковых заказа или двойное списание.
- Долгая обработка в ответе — приёмник тормозит, источник считает доставку неудачной и шлёт повтор.
- Игнор ретраев — при ошибке событие теряется, повторная отправка не настроена.
- HTTP вместо HTTPS — данные события идут открытым текстом и доступны для перехвата.
Частые вопросы
Чем вебхук отличается от обычного API?
В классическом API инициатор сам отправляет запрос и ждёт ответ — данные нужно тянуть. Вебхук переворачивает логику: вы регистрируете URL, и сервис сам присылает на него данные в момент события. Поэтому вебхук называют обратным API. На практике их используют вместе: одни данные тянут запросами, другие получают уведомлениями.
Безопасно ли принимать вебхуки из интернета?
Безопасно при правильной защите. Минимум — проверка HMAC-подписи секретным ключом и работа строго по HTTPS. Дополнительно используют секретный токен в URL и белый список IP-адресов источника. Без проверки подписи злоумышленник может прислать фейковое уведомление об оплате, поэтому для платёжных вебхуков защита обязательна.
Что будет, если мой сервер был недоступен в момент события?
Зависит от источника. Надёжные сервисы при ошибке или таймауте повторяют отправку несколько раз с нарастающей задержкой — от секунд до часов. Поэтому событие обычно не теряется, если сервер быстро восстановится. Но рассчитывать только на это рискованно: критичные события дублируют запросом к API или ставят в очередь.
Зачем обработчику вебхука быть идемпотентным?
Потому что одно событие может прийти несколько раз — из-за ретраев при сбоях или дублей на стороне источника. Если обработчик не учитывает это, повторная доставка создаст два заказа или спишет деньги дважды. Идемпотентность означает, что повторная обработка того же события не меняет результат. Обычно проверяют идентификатор события и игнорируют обработанные.
Можно ли настроить вебхуки между CRM, сайтом и чат-ботом?
Да, это типовая задача автоматизации. Сайт через вебхук передаёт заявку в CRM, платёжный шлюз сообщает CRM об оплате, чат-бот получает входящие сообщения и пишет их в карточку клиента. Все звенья связываются событиями почти в реальном времени. Настройку таких связок выполняют при внедрении CRM в BigPanda вместе с интеграцией внешних сервисов.
Чем вебхуки лучше постоянного опроса сервера?
Опрос (polling) заставляет систему каждые несколько секунд спрашивать сервер не появилось ли новое событие. Это тратит запросы впустую и даёт задержку до интервала опроса. Вебхук срабатывает мгновенно и только когда событие реально произошло, без лишнего трафика. Опрос остаётся резервным вариантом там, где источник вебхуки не поддерживает.