Вебхук это HTTP-запрос, который сервис сам отправляет на указанный вами адрес, как только произошло событие: новая заявка, оплата, сообщение боту. Обработчик по этому адресу проверяет подлинность запроса, записывает событие в журнал, сразу отвечает кодом 200 и уже в фоне создаёт сделку в CRM и уведомление в Telegram. Вебхук может прийти повторно или не по порядку, поэтому обработчик отсекает дубли по номеру события и сверяет статус через API. Для защиты используют HTTPS, секретный токен или подпись, а потерянные во время сбоя события находит ежедневная сверка.
Вебхук (webhook) это автоматическое уведомление, которое один сервис отправляет другому, как только произошло событие. Клиент оставил заявку на сайте, и сайт сам отправляет её данные на заранее указанный адрес. Там их принимает обработчик: создаёт сделку в CRM и пишет менеджеру в Telegram. Никто не проверяет почту каждые пять минут и не копирует заявки руками. Ниже разберём, как это устроено, что лежит внутри вебхука, как сделать приём надёжным и защищённым и чем вебхук отличается от обычного опроса по API.
Что такое вебхук простыми словами
Вебхук работает как звонок в дверь: вам не нужно каждые пять минут выглядывать в окно, курьер сам сообщит, что пришёл. Технически это HTTP-запрос, чаще всего методом POST, который сервис-источник отправляет на адрес сервиса-получателя в момент события.
У вебхука всегда три участника:
- Источник. Сервис, где происходит событие: форма на сайте, платёжный сервис, CRM, мессенджер.
- Адрес. Ссылка, которую вы один раз указали в настройках источника. На неё приходят уведомления.
- Обработчик. Небольшая программа по этому адресу. Она принимает данные, проверяет их и решает, что делать дальше.
Вебхук легко спутать с API. Разница в том, кто начинает разговор.
| Способ | Кто начинает | Когда приходят данные | Пример |
|---|---|---|---|
| Вебхук | Источник, сам | Сразу после события | Платёжный сервис сообщает сайту об оплате |
| Запрос к API | Получатель, когда ему нужно | По запросу | Сайт спрашивает статус платежа по номеру |
| Опрос по расписанию | Получатель, регулярно | С задержкой до следующего опроса | Скрипт каждые 5 минут проверяет, нет ли новых заказов |
Вебхук не заменяет API, а дополняет его. Вебхук говорит «что-то случилось», а за подробностями и актуальным статусом обработчик часто идёт в API. Как устроены запросы, ключи и ошибки API, разобрано в отдельной статье серии.
Как это работает: событие, вебхук, обработчик
Весь путь заявки с сайта в CRM и Telegram занимает секунды и проходит пять шагов.
- Событие. Клиент нажал «Отправить» в форме на сайте.
- Вебхук. Сайт отправляет POST-запрос с данными заявки на адрес обработчика.
- Приём. Обработчик проверяет, что запрос настоящий, записывает его в журнал и сразу отвечает кодом 200: «получил».
- Обработка. В фоне обработчик создаёт сделку в CRM по её API и получает номер сделки.
- Уведомление. Обработчик отправляет менеджеру сообщение в Telegram со ссылкой на сделку.
Обратите внимание на шаг 3. Многие источники ждут ответа недолго. Например, в документации GitHub сказано отвечать кодом 2xx в течение 10 секунд, иначе доставка считается неудачной. Поэтому медленную работу выносят в фон, а источнику отвечают сразу.
Что внутри вебхука: пример тела запроса
Вебхук несёт данные в теле запроса, обычно в формате JSON: это текст из пар «название поля: значение». Состав полей задаёт источник, поэтому у каждого сервиса он свой. Так может выглядеть заявка с сайта (пример, поля условные):
{ "event": "lead.created", "event_id": "f3a9c2", "created_at": "2026-10-27T11:42:05+03:00", "lead": { "name": "Ирина", "phone": "+7 900 000-00-00", "page": "/dostavka/", "utm_source": "yandex" } }
Здесь есть всё, что пригодится дальше: тип события, его уникальный номер, время и сами данные. Номер события нужен, чтобы не создать одну заявку дважды, а страница и метка источника рекламы помогут понять, откуда пришёл клиент.
Посмотрите, как выглядят уведомления у разных источников.
- Тело: { "event": "lead.created", "event_id": "f3a9c2", "lead": { "name": "Ирина", "phone": "+7 900…" } }
- Формат задаёте вы: добавьте номер события и время, они нужны для защиты от дублей и разбора сбоев.
- Тело ЮKassa: { "type": "notification", "event": "payment.succeeded", "object": { "id": "…", "status": "succeeded", "amount": {…} } }
- Правило: перед отгрузкой запросите статус платежа через API. Ответ на уведомление: код 200.
- Тело: { "update_id": 1001, "message": { "chat": { "id": … }, "text": "Хочу записаться на пятницу" } }
- Защита: при настройке вебхука задайте secret_token и сверяйте заголовок X-Telegram-Bot-Api-Secret-Token.
- Тело: { "event": "deal.stage_changed", "deal_id": 48213, "stage": "paid" }
- Часто приходит мало данных: только номер и событие. Подробности обработчик запрашивает через API CRM.
Вывод: в каждом вебхуке ищите три вещи: что случилось, уникальный номер события и номер объекта. Остальное при необходимости можно получить через API.
Пример: заявка с сайта сама попадает в CRM и Telegram
Разберём типичную задачу небольшой компании: заявки с формы должны появляться в CRM, а менеджер должен узнавать о них сразу, даже если CRM у него не открыта.
| Шаг | Что настроить | На что обратить внимание |
|---|---|---|
| Форма на сайте | Отправку вебхука на адрес обработчика после успешной отправки формы | Передавать страницу, метки рекламы и согласие на обработку данных |
| Обработчик | Проверку секрета, журнал, очередь, ответ 200 | Адрес только по HTTPS, секрет не в ссылке |
| CRM | Создание контакта и сделки по API | Поиск дубля по телефону, ответственный менеджер |
| Telegram | Бота, который пишет в рабочий чат или лично менеджеру | В сообщении имя, услуга и ссылка на сделку, без лишних персональных данных |
| Сбой | Повторы при ошибке CRM и оповещение ответственному | Заявка не должна теряться, даже если CRM недоступна час |
Почему не отправлять заявку прямо из формы в CRM и в Telegram? Можно, но тогда при сбое одной из систем заявка теряется без следа. Обработчик с журналом даёт одну точку, где видно каждую заявку и её судьбу. Подробно о том, какие поля передавать с заявкой и как проверить подключение на тестовых заявках, рассказано в статье о подключении CRM к сайту.
Если клиенты пишут вам и в Telegram, тот же механизм работает в обратную сторону. Telegram отправляет боту вебхук на каждое новое сообщение, а обработчик создаёт обращение в CRM. По правилам Telegram Bot API бот получает обновления либо вебхуком, либо опросом, оба способа одновременно не работают.
Вебхук или опрос: что выбрать
Вебхук выбирают, когда важно узнать о событии сразу и событий немного относительно времени. Опрос нужен, когда у источника нет вебхуков или данные меняются постоянно, как остатки на складе.
Как читать: при опросе раз в N минут о заявке узнают в среднем через N/2 минут, а большинство запросов возвращаются пустыми. Вебхук отправляется только когда есть событие и приходит сразу. Опрос раз в час или ночная сверка остаются полезными как страховка: они находят то, что вебхук не донёс.
На практике их сочетают. Вебхук даёт скорость, а редкий опрос или ночная сверка ловят то, что потерялось. Как выбрать частоту для каждого потока данных, подробно разобрано в статье о выборе частоты обновления.
Где ещё вебхуки экономят время небольшой компании
Заявка с сайта самый частый, но не единственный случай. Вебхук полезен везде, где событие в одной системе должно сразу запустить действие в другой, а сотрудник сейчас делает это вручную.
| Событие | Что происходит автоматически | Что снимает с людей |
|---|---|---|
| Оплата прошла | Заказ получает статус «Оплачен», склад видит задачу на сборку | Проверку выписки и ручную смену статуса |
| Оплата отменена или возвращена | Сделка возвращается на этап, менеджер получает сообщение | Сверку возвратов в конце дня |
| Клиент записался онлайн | Запись появляется в CRM, мастер получает уведомление | Перенос записей из формы в календарь |
| Сделка перешла в этап «Договор» | Готовится черновик договора по шаблону | Заполнение реквизитов вручную |
| Пришло сообщение боту | Создаётся обращение с историей переписки | Поиск клиента и копирование сообщений |
| Заказ передан в доставку | Клиент получает письмо или сообщение с номером отслеживания | Ответы на вопрос «где мой заказ» |
Перед тем как настраивать вебхук, проверьте в документации источника, есть ли нужное событие. Вебхуки бывают только там, где их сделал разработчик сервиса. Если события нет, остаётся опрос по API или выгрузка по расписанию.
Надёжность: повторы, дубли и порядок событий
Вебхук может прийти дважды, прийти не по порядку или не прийти вовсе, если ваш адрес был недоступен. Хороший обработчик готов ко всем трём случаям.
- Повторы. Если ваш адрес не ответил 2xx, источник обычно повторяет отправку. ЮKassa, например, повторяет уведомление в течение 24 часов после события, Telegram тоже делает несколько попыток. Значит, короткий сбой не страшен, если обработчик потом поднимется.
- Дубли. Повтор может прийти, даже если первое уведомление вы уже обработали, например при обрыве связи на ответе. Храните номера обработанных событий и пропускайте уже известные.
- Порядок. Уведомление «оплата отменена» может прийти раньше, чем «оплата создана». Перед важным действием запросите актуальный статус объекта через API.
- Потери. Если обработчик лежал дольше, чем источник повторяет, событие пропадёт. Ночная сверка количества заявок и оплат найдёт такие пропуски.
Безопасность: как убедиться, что запрос настоящий
Адрес обработчика доступен из интернета, поэтому на него может прийти что угодно. Проверка подлинности обязательна, особенно для оплат.
| Способ | Как работает | Пример из документации |
|---|---|---|
| Секретный токен | Источник присылает в заголовке заранее заданную строку, обработчик её сверяет | Telegram передаёт значение secret_token в заголовке X-Telegram-Bot-Api-Secret-Token |
| Подпись | Источник вычисляет подпись тела запроса общим секретом, обработчик пересчитывает и сравнивает | GitHub передаёт подпись HMAC SHA-256 в заголовке X-Hub-Signature-256 |
| Адреса отправителя | Обработчик принимает запросы только с IP-адресов источника | ЮKassa публикует список своих IP-адресов |
| Сверка через API | Обработчик не верит уведомлению на слово и запрашивает статус | ЮKassa рекомендует сверять статус объекта через API |
И ещё три правила. Адрес обработчика только по HTTPS: Telegram, например, принимает вебхуки на портах 443, 80, 88 и 8443, а ЮKassa требует HTTPS и TLS не ниже 1.2. Секрет не вставляют в саму ссылку, где он попадает в журналы серверов. Принимают только ожидаемые поля и разумный размер тела. Как устроен сертификат для HTTPS и почему он может внезапно истечь, описано в статье что такое SSL-сертификат.
Как проверить, что вебхук работает
Вебхук проверяют на тестовых событиях до запуска и потом следят за ним каждый день.
- Тестовая заявка. Отправьте форму сами и проверьте: запись в журнале обработчика, сделка в CRM, сообщение в Telegram, всё с одинаковыми данными.
- Тест сбоя. Временно отключите доступ к CRM и отправьте заявку. Она должна дождаться в очереди и появиться в CRM после восстановления, а ответственный должен получить оповещение.
- Тест дубля. Отправьте то же событие повторно. Вторая сделка появиться не должна.
- Тест подделки. Отправьте запрос без секрета или с неверной подписью. Обработчик должен его отклонить.
- Ежедневная сверка. Сколько заявок пришло на сайт и сколько сделок появилось в CRM. Расхождение повод разбираться.
Кто отвечает за вебхуки после запуска
Вебхук легко настроить и легко забыть. Через год никто не помнит, куда уходят уведомления об оплате, а смена домена или переезд сайта тихо ломает обмен. Поэтому у каждого вебхука должен быть хозяин и короткая запись в документации.
- Где настроен. В каком сервисе, в каком разделе настроек и под какой учётной записью.
- Куда отправляет. Адрес обработчика и какие события на него подписаны.
- Где лежит секрет. Не сам секрет, а место хранения и кто может его поменять.
- Кто получает оповещения. Имя ответственного и запасной контакт на время отпуска.
- Что проверить при изменениях. Переезд сайта, смена домена, обновление CRM, новые поля в форме.
Учётные записи, в которых настроены вебхуки, должны принадлежать компании, а не подрядчику. Тогда смена исполнителя не превращается в поиск, кто и где когда-то что-то подключил.
Чек-лист: надёжен ли ваш приёмник вебхуков
Пройдитесь по пунктам для каждого вебхука, который у вас уже работает или только планируется.
Типичные ошибки
- Долгая обработка до ответа. Источник не дождался ответа, посчитал доставку неудачной и прислал повтор.
- Нет защиты от дублей. Каждый повтор создаёт новую сделку.
- Нет проверки подлинности. Любой, кто узнал адрес, может создать заявку или «оплату».
- Секрет в ссылке. Он оседает в журналах и пересылках.
- Нет журнала. Непонятно, пришёл ли вебхук и что с ним стало.
- Вера уведомлению на слово. Заказ отгружают по вебхуку об оплате без сверки статуса.
- Нет сверки. События, потерянные во время сбоя, никто не замечает.
Частые вопросы
Что такое вебхук простыми словами?
Это уведомление, которое сервис сам отправляет на ваш адрес, как только произошло событие. Например, сайт сообщает обработчику о новой заявке, а платёжный сервис об оплате. Никому не нужно постоянно проверять, нет ли новостей.
Чем вебхук отличается от API?
При запросе к API разговор начинает получатель: он спрашивает данные, когда они ему нужны. Вебхук начинает источник в момент события. Обычно их используют вместе: вебхук сообщает о событии, а подробности обработчик запрашивает через API.
Что будет, если адрес обработчика был недоступен?
Многие сервисы повторяют отправку. Например, ЮKassa повторяет уведомление в течение 24 часов после события. Если сбой длился дольше, событие можно потерять, поэтому нужна ежедневная сверка с источником.
Почему из-за вебхука в CRM появились дубли?
Источник прислал повтор, а обработчик создал запись ещё раз. Повтор бывает, если ответ 200 не дошёл или ушёл слишком поздно. Решение: хранить номера обработанных событий и пропускать уже известные.
Как защитить вебхук от поддельных запросов?
Принимать запросы только по HTTPS, проверять секретный токен или подпись в заголовке, по возможности ограничить IP-адреса отправителя, а важные события вроде оплаты сверять через API источника.
Можно ли получать сообщения Telegram-бота через вебхук?
Да. В Telegram Bot API бот получает обновления либо через вебхук, либо опросом методом getUpdates, одновременно эти способы не работают. Для вебхука нужен адрес по HTTPS на одном из портов 443, 80, 88 или 8443.
Нужен ли программист, чтобы настроить вебхук?
Указать адрес в настройках сервиса можно самому. Но обработчик с проверкой подлинности, журналом, очередью и защитой от дублей пишет разработчик, иначе заявки будут теряться при первом сбое.
