Webhook - это способ сообщить системе, что что-то произошло. Внешний сервис отправляет HTTP-запрос на заранее настроенный адрес: пришла заявка, создан тикет, изменился статус сделки, пользователь написал в Telegram или прошла оплата.
В отличие от polling, где система сама постоянно спрашивает API "есть ли что-то новое", webhook работает как уведомление. Событие произошло - сервис сам отправил данные. Это быстрее, экономнее и удобнее для автоматизаций.
Для ИИ-агента webhook часто является входной точкой. Например, сообщение из Telegram приходит на webhook, workflow проверяет данные, вызывает агента, получает ответ и отправляет его пользователю. Или форма на сайте отправляет webhook, а агент квалифицирует лид и создает сделку в CRM.
Webhook нельзя принимать без проверок. Нужно убедиться, что запрос пришел от нужного сервиса: проверить секрет, подпись, токен, IP-ограничения или другой механизм доверия. Также важно валидировать payload и не запускать опасные действия по непроверенным данным.
Частая проблема webhook - повторы. Сервис может отправить одно событие несколько раз, если не получил ответ или была ошибка сети. Поэтому нужны idempotency key, журнал обработанных событий и логика, которая не создает дубли сделок, задач или сообщений.
Практичная структура webhook-события: event_id, source_system, event_type, received_at, signature_status, payload, normalized_payload, processing_status, retry_count, workflow_id и audit_log_id.
Примеры
- Telegram отправляет webhook, когда пользователь пишет боту.
- CRM отправляет webhook, когда создан новый лид или изменилась стадия сделки.
- Форма на сайте отправляет webhook с именем, телефоном и текстом заявки.
- Платежный сервис отправляет webhook после успешной оплаты или ошибки платежа.
- GitHub отправляет webhook, когда создан pull request или завершился workflow.
Где используется
- Запуск ИИ-агента по сообщению из Telegram, WhatsApp, Slack или чата.
- Обработка заявок с сайта и создание лидов в CRM.
- Автоматизация helpdesk: новый тикет, комментарий, смена статуса.
- Интеграция с платежами, доставкой, формами и внешними API.
- Запуск n8n, Make, Zapier или Flowise workflow по событию.
- Обновление таблиц, задач и отчетов без ручного копирования.
- Связка tool calling и write-back во внешние системы.
Связанные термины
Частые вопросы
Что такое webhook простыми словами?
Это специальный URL, на который другой сервис отправляет данные, когда происходит событие. Например, пользователь написал боту, и Telegram отправил сообщение на ваш webhook.
Чем webhook отличается от API?
API часто вызывают вручную или по расписанию, чтобы забрать данные. Webhook работает наоборот: внешний сервис сам присылает событие на ваш URL, когда что-то произошло.
Что нужно проверять во входящем webhook?
Нужно проверить подпись или секрет, источник, формат данных, обязательные поля, event_id, права действия и лимиты. Нельзя доверять webhook только потому, что запрос пришел на правильный адрес.
Почему webhook может прийти несколько раз?
Если внешний сервис не получил подтверждение или была ошибка сети, он может повторить отправку. Поэтому обработчик должен быть идемпотентным и не создавать дубли.
Как webhook используется в ИИ-агентах?
Webhook запускает агента по событию: новое сообщение, заявка, тикет или изменение в CRM. Дальше агент анализирует данные и выполняет разрешенные действия через workflow.
