Вебхук (Webhook): что это такое и как работает

Webhook (вебхук) — это механизм автоматического оповещения одной системы о событиях, произошедших в другой. В отличие от классического API, где программа сама регулярно запрашивает обновления, вебхук отправляет данные в виде HTTP-запроса мгновенно в момент наступления события. Это позволяет сервисам обмениваться информацией в реальном времени, экономя вычислительные ресурсы серверов и сетевой трафик.

Как это работает на практике

При интеграции внешних платформ архитектура доставки событий через вебхуки накладывает жесткие рамки на серверную сторону принимающей системы.

Когда происходит триггерное действие — например, пользователь пишет первое сообщение боту — платформа-отправитель формирует пакет данных и отправляет его на указанный URL-адрес (эндпоинт). В этот массив передается системная информация: идентификатор сообщения, численный идентификатор абонента (user_id), временная метка Unix timestamp, текст и URL-ссылки на медиавложения.

При первом контакте номер мобильного телефона скрыт настройками конфиденциальности; передаются только открытые данные профиля (имя, фамилия, аватар). Телефонный номер попадет в систему только после явного нажатия пользователем интерактивной кнопки request_contact. Принимающий эндпоинт CRM-системы обязан обработать этот запрос и вернуть ответ с HTTP-кодом 200 OK в течение строгого интервала тайм-аута, который обычно составляет 30 секунд.

Когда это нужно

Технология критически важна для процессов, требующих мгновенной реакции на действия пользователей или изменения в сторонних базах. Вебхуки применяются для создания лидов при заполнении форм на сайте, обновления статусов заказов в интернет-магазинах, маршрутизации входящих обращений и запуска триггерных рассылок.

Если перед бизнесом стоит задача разбирать переписки без участия менеджера и моментально фиксировать новые заявки, именно вебхуки обеспечат бесперебойную доставку сообщений из мессенджера прямо в воронку продаж. Также этот инструмент незаменим, когда настраиваются amocrm интеграции для двусторонней синхронизации сделок: как только сотрудник переводит карточку клиента на следующий этап, система мгновенно уведомляет об этом складскую программу или сервис аналитики без необходимости постоянно опрашивать базу данных.

Когда не нужно

Использование вебхуков неоправданно для задач массовой выгрузки исторических данных или непрерывной фоновой синхронизации огромных массивов информации. Если принимающий сервер обладает низкой пропускной способностью или нестабильным соединением, поток входящих HTTP-запросов приведет к потере данных.

Возврат кодов ошибок или превышение временного порога считается платформой сбоем доставки. В таком случае отправитель запускает алгоритм повторных запросов. Например, сервер выполняет до 10 повторов с экспоненциальной прогрессией задержки: первая попытка происходит через 60 секунд, вторая — через 150 секунд, третья — через 375 секунд. Лавинообразные повторные запросы быстро перегружают коннекторы CRM-систем.

Особенно часто сбои очередей возникают при передаче медиафайлов предельного объема. Хотя спецификация может декларировать поддержку файлов до 4,0 ГБ, на практике обработка вложений размером свыше 1,5 ГБ почти всегда превышает лимит времени ответа в 30 секунд. Для таких сценариев надежнее использовать классический REST API.

Чек-лист настройки надежного вебхука

Обеспечьте асинхронную обработку: эндпоинт должен мгновенно возвращать HTTP-код 200 OK, а сам парсинг и запись данных в базу выполнять фоновым процессом, чтобы уложиться в 30-секундный тайм-аут.

Настройте проверку безопасности: используйте заголовок авторизации входящих хуков (например, X-Max-Bot-Api-Secret длиной от 5 до 256 символов), чтобы исключить подмену данных злоумышленниками.

Реализуйте защиту от дубликатов: каждая входящая заявка должна проверяться по уникальному идентификатору сообщения, так как при кратковременных сетевых сбоях отправитель может прислать один и тот же пакет данных несколько раз.

Установите лимиты на обработку медиа: настройте фильтрацию входящих файлов по размеру и формату, чтобы загрузка тяжелых документов (свыше 1,5 ГБ) не блокировала общую очередь сообщений.

Частые вопросы

В чем главная разница между API и Webhook?

API работает по принципу регулярного опроса (pull): клиент сам обращается к серверу с вопросом о наличии новых данных. Webhook использует принцип проталкивания (push): сервер самостоятельно отправляет данные клиенту ровно в тот момент, когда происходит целевое событие.

Что произойдет, если CRM-система временно недоступна и не примет вебхук?

Отправитель зафиксирует сетевую ошибку. Качественные платформы не удаляют сообщение сразу, а используют механизм отказоустойчивости, выполняя до 10 попыток повторной отправки с увеличивающимся интервалом (60, 150, 375 секунд и так далее).

Можно ли получить номер телефона клиента при первом входящем вебхуке из мессенджера?

Нет, при первом обращении передаются только системный идентификатор (user_id) и открытые данные профиля. Номер телефона скрыт настройками конфиденциальности и передается только после того, как пользователь нажмет специальную кнопку запроса контакта внутри интерфейса.

Как правильно спроектировать архитектуру для приема вебхуков?

Главное правило — скорость ответа. Сервер должен подтвердить прием пакета за доли секунды, а всю тяжелую логику вынести в отдельные фоновые процессы. Подробнее про лимиты, тайм-ауты и технические требования можно прочитать в материале про чат-бот MAX.