Словарь ClaudeLab
Что такое вебхук
Вебхук - это автоматическое HTTP-уведомление, которое один сервис отправляет другому при наступлении события. Вместо постоянной проверки «что изменилось» принимающая система получает запрос с данными сразу после оплаты, новой заявки, смены статуса или другого настроенного действия.
Простыми словами
Вебхук похож на звонок курьера в дверь. Вам не нужно каждые две минуты выходить на лестницу и проверять, приехал ли заказ. Когда событие произошло, курьер сам подаёт сигнал. После звонка вы проверяете, кто пришёл, и выполняете нужное действие.
Зачем это бизнесу
Передаёт событие без опроса
Принимающий сервис не тратит запросы на постоянную проверку статуса. Источник сам отправляет сообщение в момент изменения, а обработчик запускается только тогда, когда есть работа.
Ускоряет связанный процесс
Подтверждение оплаты может сразу передать заказ на сборку, а новая заявка - создать сделку в CRM. Задержка зависит только от доставки и обработки запроса. Ждать очередную выгрузку не требуется.
Разделяет системы
Источник знает только адрес получателя и формат события. Он не управляет внутренней логикой другой системы, поэтому обработчик можно менять, не переписывая сервис, который отправляет уведомление.
Поддерживает повторную доставку
Рабочая схема учитывает временный сбой: источник повторяет запрос или сохраняет событие для новой попытки. Получатель обрабатывает повтор безопасно, чтобы один платёж не создал два заказа.
Как это выглядит на практике
| Событие | Реакция получателя |
|---|---|
| Оплата подтверждена | Магазин проверяет подпись уведомления, находит заказ и переводит его в следующий статус один раз. |
| Создана заявка | Интеграция добавляет контакт в CRM, сохраняет источник и возвращает успешный ответ отправителю. |
| Документ подписан | Система фиксирует событие, уведомляет ответственного и открывает следующий этап согласования. |
| Получатель недоступен | Источник отмечает неудачную доставку и повторяет её по своей политике без потери исходных данных. |
Вебхуки часто становятся связующим звеном между оплатой, сайтом, CRM и уведомлениями. Проектирование таких цепочек входит в задачи по автоматизации бизнеса: отдельно проверяются подпись, повторная доставка, дубли и поведение при недоступности сервиса.
Частые вопросы
- Чем вебхук отличается от API?
- API описывает способы обратиться к сервису за данными или действием. Вебхук использует веб-запрос в обратную сторону: сервис сам уведомляет подписчика о событии. На практике вебхук сообщает, что произошло, а API помогает запросить детали.
- Что находится внутри вебхука?
- Обычно идентификатор и тип события, время, данные объекта и служебная информация для проверки. Состав задаёт отправитель. Получатель не должен полагаться на поля, которых нет в официальном контракте.
- Как защитить вебхук?
- Проверять подпись или секрет, использовать защищённое соединение, ограничивать размер запроса и не доверять входным полям до валидации. Секрет нельзя печатать в открытый журнал или возвращать в сообщении об ошибке.
- Почему один вебхук иногда приходит несколько раз?
- Отправитель мог не получить подтверждение и повторить доставку. Это нормальная защита от потери события. Обработчик хранит идентификатор операции и делает повторный запрос безопасным, не создавая дубли.