Мигом

amoCRM и интеграции

Вебхук простыми словами: как сервис сам сообщает о событии

Разбираем, как сервис сам сообщает вашей системе о событии, чем это отличается от опроса API и что проверить, прежде чем подрядчик включит вебхук.

Коротко: вебхук — это автоматический запрос, который сервис сам отправляет на адрес вашей системы, когда что-то произошло: посетитель написал в чат, сделка перешла на другой этап. Так CRM узнаёт о новом сообщении почти сразу и не опрашивает сервис по расписанию. Перед запуском договоритесь с подрядчиком, как защитить запрос, что будет при сбое и как проверить связку на тестовом событии.

Что такое вебхук простыми словами

Вебхук (webhook) — способ, которым один сервис сам сообщает другому о событии. В настройках сервиса один раз указывают адрес вашей системы и выбирают события. При каждом таком событии сервис отправляет на этот адрес HTTP-запрос (обычное обращение по интернету, как при открытии страницы) с данными о том, что случилось. Так механизм описан в документации GitHub, сервиса для разработчиков.

В документации amoCRM вебхуки названы уведомлениями сторонним приложениям о событиях: сделку или контакт добавили, изменили или удалили, сменили ответственного или статус сделки.

Допустим, в пятницу в 23:10 посетитель пишет в чат на странице доставки, а менеджеры уже ушли. Если чат связан с CRM через вебхук, в понедельник утром обращение будет ждать менеджера вместе с вопросом и страницей, с которой написал посетитель.

Чем вебхук отличается от запроса к API

Разница в том, кто начинает обмен. API (программный интерфейс) — набор команд, через которые программы обмениваются данными. Запрос к API отправляет ваша система, когда ей нужны данные, а вебхук присылает сам сервис, как только что-то произошло.

Без вебхука CRM узнаёт о новых сообщениях опросом: например, раз в несколько минут спрашивает сервис чата через API, нет ли нового. Похоже на заказ в магазине: можно каждый час звонить и спрашивать, готов ли он, а можно оставить номер и ждать звонка. Сравнение по обзору вебхуков GitHub:

Опрос через APIВебхук
Когда CRM узнаёт о событиипри следующем опросепочти сразу
Затратызапросы идут, даже когда нового нетменьше: запрос приходит только при событии
Когда подходитданные нужны один раз или изредкаследить нужно за многими объектами

Обычно вебхук и API работают вместе. По документации Битрикс24 событие сообщает только о факте изменения: приходит, например, номер сделки, а сами данные ваша система получает отдельным запросом к API.

Что приходит в вебхуке: пример с чатом и CRM

В вебхуке обычно приходят название события, время и данные о том, что произошло, а часто и уникальный номер события.

Условный пример: посетитель спрашивает в чате на странице доставки: «Привезёте завтра в Подольск?» Сервис чата отправляет POST-запрос (метод для отправки данных) на адрес, который дал подрядчик, например https://crm.example.com/hooks/chat. Там работает обработчик, небольшая программа вашей системы: он проверяет подпись, сохраняет событие, отвечает кодом 200 (запрос принят) и создаёт обращение в CRM.

{
  "event": "message.created",
  "id": "evt-8f41c2",
  "time": "2026-10-09T23:10:41+03:00",
  "chat": "chat-1042",
  "page": "https://example.com/dostavka",
  "text": "Привезёте завтра в Подольск?"
}

Это тело запроса, то есть его содержимое, в формате JSON: набор пар «поле: значение». Поле event называет событие, id хранит его номер, по которому отсеивают повторы, а chat связывает сообщение с разговором. Имени и телефона посетителя в примере нет намеренно. У настоящих сервисов поля и формат свои: вебхуки CRM в amoCRM и Битрикс24 присылают данные как обычная веб-форма, в формате x-www-form-urlencoded, а API чатов amoCRM шлёт JSON.

В теле запроса бывают и персональные данные: в примере вебхука из API чатов amoCRM у получателя есть поля с телефоном и email. По п. 1 ст. 3 Федерального закона от 27.07.2006 № 152-ФЗ персональные данные — это «любая информация, относящаяся к прямо или косвенно определенному или определяемому физическому лицу». Оператор по ч. 1 ст. 19 того же закона «обязан принимать необходимые правовые, организационные и технические меры» для их защиты «от неправомерного или случайного доступа к ним».

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

Входящий и исходящий вебхук: кто кому отправляет

Слова «входящий» и «исходящий» зависят от того, с чьей стороны смотреть: для сервиса чата запрос в CRM исходящий, для CRM тот же запрос входящий.

В Битрикс24 термины закреплены в описании входящих и исходящих вебхуков: «Входящий вебхук вызывает методы REST API от имени сотрудника, который его создал. Исходящий вебхук отправляет событие Битрикс24 на URL вашего обработчика». Получается, что входящий вебхук там — секретный адрес, по которому внешняя система сама обращается к Битрикс24, например добавляет контакт, а уведомления о событиях шлёт исходящий.

В amoCRM уведомления о событиях называются просто вебхуками. Администратор добавляет их в amoМаркете кнопкой «+ Webhooks», указывает «Имя», «URL» и «Событие» и нажимает «Сохранить». По терминам Битрикс24 это исходящий вебхук.

Если подрядчик говорит «настроим входящий вебхук», уточните, кто кому отправляет запрос и о каком событии.

Важно. Адрес входящего вебхука Битрикс24 содержит секретный код, по сути пароль к вебхуку. Справка Битрикс24 предупреждает: «Никому не передавайте секретный код вебхука и не указывайте его в коде страницы или скрипта. Если посторонние люди увидят этот код, они смогут получить доступ к данным вашего Битрикс24».

Как защищают вебхук: секрет и подпись

Чаще всего вебхук защищают общим секретом, строкой, которую знают только сервис и ваша система: по ней обработчик отличает настоящий запрос от поддельного. Без проверки любой, кто узнал адрес, может прислать поддельное событие, а документация платёжного сервиса Stripe напоминает, что так можно заставить систему выполнять заказы или менять записи.

Адрес вебхука может утечь. Битрикс24 предупреждает: если вызывать входящий вебхук GET-запросом, например из адресной строки браузера, его адрес может сохраниться в истории браузера, логах (служебных записях программ) и сервисах мониторинга.

Первый способ защиты: секрет приходит в каждом запросе, и обработчик сравнивает его со своим. Так проверяют исходящий вебхук Битрикс24: при его создании система показывает секретное значение, а обработчик сверяет его с полем auth[application_token] в запросе. При несовпадении документация о безопасности обработчиков велит вернуть код 403 (доступ запрещён). Похожим образом работает ключ API, который задают в настройках вебхука Tilda.

Второй способ — подпись. Сервис считает по телу запроса и секрету контрольную строку HMAC (механизм описан в RFC 2104) и кладёт её в заголовок, служебную строку запроса. Обработчик повторяет расчёт и сравнивает результат, а сам секрет по сети не передаётся.

Подпись GitHub приходит в заголовке X-Hub-Signature-256 и показывает, что запрос отправил GitHub и по дороге его не меняли. Формат вебхуков API чатов amoCRM предусматривает подпись в заголовке X-Signature: её считают по телу запроса методом HMAC-SHA1, секретом служит секрет канала. В описании вебхуков CRM в amoCRM подпись не упоминается, так что спросите подрядчика, как обработчик проверит такие запросы.

Подпись подтверждает отправителя, но содержимое не шифрует. Без HTTPS (защищённого соединения) тело запроса можно подслушать, говорится в спецификации Standard Webhooks, своде рекомендаций сообщества разработчиков. Tilda требует от обработчика HTTPS, Stripe принимает только публичные адреса HTTPS.

Что бывает при сбое: повторы и дубли

При сбое одни сервисы повторяют отправку, другие нет, и у каждого свой срок ответа и свой «успешный» код. Код ответа — трёхзначное число, которым ваша система отвечает на запрос. По справочнику MDN у успешных ответов коды от 200 до 299.

Сервис (документация на 08.10.2026)Сколько ждёт ответаЧто считает успехомПовторяет ли сам
amoCRM, вебхуки CRM2 секундыкод от 100 до 299да, ещё до четырёх попыток через 5 мин, 15 мин, 15 мин и 1 ч после предыдущей; две последние — только после ответа 499 или от 500 до 599
amoCRM, API чатов5 секундкод 200нет, вебхук отправляется один раз
Битрикс24, исходящий вебхукне указаноне указано; нет ответа или ошибка — сбойнет
Tilda, вебхук форм5 секундна тестовый запрос ждёт 200 OKещё две попытки, каждая через минуту
GitHub10 секундкод от 200 до 299нет; доставки за последние 3 дня можно повторить вручную или своим скриптом через API
Stripeсрок не назван; ответить нужно быстро, до сложной обработкикод от 200 до 299; перенаправление (код от 300 до 399) — сбойда, до трёх дней с растущими интервалами; в тестовой среде три раза за несколько часов

У вебхуков CRM в amoCRM есть и правило отключения: если за последние 2 часа не удалось больше 100 доставок, включая последнюю, вебхук отключается. Администраторы аккаунта получают уведомление, а включить вебхук снова можно в настройках: нажать «Включить», затем сохранить.

Повторы приводят к дублям. Допустим, сервис с повторами ждёт ответа 5 секунд, а ваша система создаёт обращение и отвечает через 7: событие придёт снова, и без проверки в CRM появится второе обращение. Справочник MDN среди возможных последствий повторного POST-запроса называет «оформление одного и того же заказа несколько раз».

От дублей защищаются по номеру события. Stripe советует записывать номера обработанных событий и пропускать уже записанные, у GitHub заголовок X-GitHub-Delivery при повторной доставке не меняется, у Tilda номер заявки приходит в поле tranid. По спецификации Standard Webhooks номер события часто используют как ключ идемпотентности. Идемпотентность означает, что повтор операции не меняет результат: второго обращения не будет.

Чтобы не упираться в срок ответа, обработчик сначала отвечает, а обращение создаёт потом. Рекомендации GitHub по вебхукам предлагают для этого очередь и обработку в фоне.

Что спросить у подрядчика перед запуском

Перед запуском попросите подрядчика ответить на семь вопросов и показать работу вебхука на тестовом событии.

  • События. Кто кому отправляет запрос и о каких событиях?
  • Данные. Есть ли в теле запроса имя, телефон или email посетителя, где они хранятся и кто их видит?
  • Адрес. Открывается ли адрес обработчика из интернета и работает ли по HTTPS? Требования Битрикс24 к адресу обработчика исключают localhost (адрес компьютера самого разработчика), адреса локальной сети и обработчики с самоподписанным SSL-сертификатом.
  • Подлинность. Как обработчик отличает настоящий запрос от поддельного и где хранится секрет? В адресе вебхука, коде сайта и логах его быть не должно.
  • Сбои. Сколько сервис ждёт ответа и повторяет ли отправку?
  • Дубли. Как обработчик узнаёт уже обработанное событие?
  • Журнал. Где видно, какие запросы ушли и что на них ответили, и кто узнает, если вебхук отключится?

В журнале доставок GitHub за последние 3 дня видны заголовки и тело запроса, время отправки и ответ вашей системы. У Tilda ошибки отправки собраны в разделе «Заявки» → «Журнал ошибок».

На тестовом событии связку проверяют в четыре шага:

  1. Возьмите вымышленные данные: тестовый посетитель, телефон из нулей.
  2. Запустите событие в самом сервисе. Для проверки вебхука в amoCRM совершите действие, выбранное при его создании, и посмотрите, дошли ли данные до вашей системы. Вебхук форм Tilda сразу после подключения сам шлёт запрос test=test.
  3. Найдите запрос в журнале и посмотрите, что ответила ваша система.
  4. Повторите доставку того же события, например кнопкой «Redeliver» в журнале GitHub: в CRM должно остаться одно обращение.

Как это устроено в чате Мигом

Подключить чат Мигом к CRM, сервису поддержки или внутренним инструментам можно через API и вебхуки: так передают обращения, сообщения и историю переписки. Для разработчиков есть REST API и история переписки, вебхуки с подписью и повторами, JS API виджета с типами TypeScript; API и вебхуки доступны на любом тарифе. Способ подключения зависит от возможностей вашей системы и подбирается вместе с вами, а готовой интеграции с каждой CRM не обещают.

Основная интеграция чата Мигом — amoCRM: менеджер отвечает прямо из карточки сделки, а три способа подключить чат на сайте к amoCRM разобраны отдельно. Какие рабочие места есть у команды и как подключить другую систему, описано на главной, а тарифы собраны в разделе о ценах.

Итог. Надёжным вебхук делают проверка подлинности, HTTPS, быстрый ответ и защита от дублей, а повторы при сбое у каждого сервиса свои. Перед запуском пройдите с подрядчиком семь вопросов и проверьте связку одним тестовым событием с вымышленными данными.

FAQ

Вебхук — это API?

Да, вебхуки считают частью API сервиса, только запрос идёт в обратную сторону: спецификация Standard Webhooks называет их своего рода «обратным API» (в переводе).

Что такое callback и при чём тут вебхук?

Callback, или обратный вызов, работает по принципу «сообщите, когда будет готово»: вы оставляете адрес, и система обращается по нему позже. По формулировке Standard Webhooks, вебхуки и есть общее название HTTP callbacks, обратных вызовов по протоколу HTTP.

Что такое webhook secret и где его хранить?

Это секретная строка, общая для сервиса и вашей системы: по ней обработчик проверяет подлинность запроса. Рекомендации GitHub по вебхукам советуют делать её случайной и сложной для подбора, хранить в защищённом месте, доступном вашему обработчику, и не вписывать секреты в адрес вебхука.

Нужен ли программист, чтобы настроить вебхук?

Для отправки обычно нет: в amoCRM вебхук добавляет администратор в amoМаркете, в Битрикс24 исходящий вебхук создают в разделе «Разработчикам». Принимает запросы обработчик на вашей стороне, и его пишет программист, если готовой интеграции между системами нет.

Источники

Все статьи блога