Вебхук: что это, чем отличается от API и как принимать его без своего сервера

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

Вебхук — это HTTP-запрос, который сервис отправляет на указанный вами адрес, когда в нём происходит событие: пришёл платёж, оставлена заявка, изменилась карточка в CRM. GitHub в документации описывает вебхуки как способ уведомлять внешний сервер о событиях: вы подписываетесь один раз и дальше получаете данные автоматически.

Аналогия из быта — доставка. Можно каждый час звонить в магазин и спрашивать, приехал ли заказ. Можно оставить магазину номер телефона, и он позвонит, когда заказ готов. Номер телефона здесь — адрес вебхука, звонок — запрос с данными о событии.

У вебхука две стороны: отправитель, то есть сервис, в котором происходят события, и получатель — программа по вашему адресу. Получатель должен быть доступен из интернета, иначе отправителю некуда доставлять запрос.

Вебхук, API-запрос и опрос: в чём разница

В запросе к API вопрос задаёте вы, в вебхуке — сервис. Опрос — это те же запросы к API, которые ваша программа повторяет по таймеру, чтобы не пропустить новое.

GitHub пишет, что вебхуки требуют меньше усилий и ресурсов, чем опрос, и лучше масштабируются: при опросе многих объектов быстро исчерпывается лимит запросов к API. Запрос к API, по той же документации, остаётся разумным выбором, когда данные нужны редко или по небольшому постоянному набору объектов. Telegram даёт боту оба способа получать обновления, getUpdates и setWebhook, и в руководстве отмечает, что у getUpdates нет ничего плохого.

Как выглядит входящий запрос

Это обычный POST-запрос: в заголовках служебные данные, в теле — описание события, чаще всего в формате JSON. Условный пример заявки с формы:

{
  "event": "lead.created",
  "id": 1024,
  "created_at": "2026-10-09T10:15:00Z",
  "data": {
    "name": "Anna",
    "phone": "+79000000000",
    "comment": "callback"
  }
}

Поля у каждого отправителя свои. ЮKassa присылает тело с полями type, event и object: название события строится как «объект.статус», например payment.succeeded, а в object лежат данные платежа на момент события. Telegram отправляет по HTTPS JSON-объект Update при каждом новом обновлении для бота. Исходящий вебхук Битрикс24 передаёт параметры формы event, data, ts и auth. Образец тела берите из документации отправителя.

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

Где встречаются вебхуки

Вебхуки встречаются в самых разных сервисах. Примеры из их официальной документации:

• Оплаты. В ЮKassa адрес и события задают в личном кабинете, в разделе «Интеграция», пункт «HTTP-уведомления». Stripe использует вебхуки для асинхронных событий, например когда банк клиента подтвердил платёж.
• Боты и мессенджеры. У Telegram для этого метод setWebhook; пока вебхук задан, getUpdates не работает.
• CRM. Исходящие вебхуки Битрикс24 сообщают о событиях портала.
• Код и репозитории. События в репозитории GitHub запускают сборку, уведомление или выкладку.
• Формы и заявки. Форма на вашем сайте может отправлять заявку на адрес вашего приложения.

Что такое вебхук в Битрикс24

В Битрикс24 два вида вебхуков. Входящий вызывает методы REST API портала от имени сотрудника, который его создал: к порталу обращается внешняя система или скрипт. Адрес входящего вебхука содержит секретный код, и Битрикс24 предупреждает, что такой адрес нельзя отдавать третьим лицам и публиковать в клиентском коде.

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

Готового приёмника под Битрикс24 в Allokai нет. Обработчиком может стать приложение, которое агент напишет под вашу задачу, как и для любого другого сервиса. Как подключить CRM к агенту, описано на странице Битрикс24 MCP.

Как принять вебхук без своего сервера

Опишите в чате, что и откуда приходит и что с этим делать. Агент напишет приложение с входящим HTTP-адресом, запустит его в облаке Allokai и назовёт адрес, который нужно вставить в настройки отправителя. Своего сервера для этого не нужно.

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

Что получится на выходе

• Приложение с входящим адресом: оно принимает запрос, проверяет его и отвечает отправителю.
• Таблица в вашей базе Postgres, куда пишется каждый принятый запрос.
• Действие после приёма: строка в xlsx, сообщение вам или запрос в другой сервис через подключение, которое агент пишет сам.
• Постоянная ссылка на приложение. Новая версия заменяет старую, старую можно вернуть.

Пример готовой системы для заявок — учёт заявок для небольшой команды.

Что нужно от вас

• Описание задачи: какой сервис шлёт, какое событие, что сделать с данными. Хорошо, если есть ссылка на документацию отправителя с образцом тела.
• Адрес нужно вставить в настройки отправителя. Это можете сделать вы. Если дадите агенту доступ к кабинету, он сделает это в своём браузере; пароль вводится в защищённую форму, значение шифруется, модель его не видит. Проверку «я не робот» агент не обходит.
• Секрет подписи, если отправитель его выдаёт. Его тоже вводят в защищённую форму; в обычное сообщение вставлять его нельзя.
• Решение, куда записывать данные и кого уведомлять.

Безопасность: подпись, секрет в адресе, повторные доставки

Запрос на адрес приёмника может прислать любой, кто этот адрес узнал, поэтому первая задача — убедиться, что запрос пришёл от отправителя. Надёжнее всего подпись: отправитель считает её от тела запроса и общего секрета, получатель считает так же и сравнивает.

Сведения в таблице взяты с официальных страниц отправителей на 9 октября 2026.

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

Три правила, которые стоит заложить в приложение:

1. Сравнивать подпись с телом запроса в том виде, в каком оно пришло, до разбора JSON. GitHub просит не менять тело и заголовки до проверки, а подписи сравнивать за постоянное время: обычное сравнение через == он не рекомендует.
2. Хранить идентификатор каждого события и пропускать уже обработанные: Stripe документирует, что одно событие может прийти несколько раз. Идентификатор события GitHub, заголовок X-GitHub-Delivery, при повторной доставке не меняется.
3. Отвечать успешным кодом сразу, а тяжёлую работу делать после ответа.

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

Как проверить, что запрос дошёл

Отправьте тестовый запрос и проверьте, что запись появилась. Порядок такой:

1. Попросите агента отправить тестовый запрос со своей Linux-машины на адрес приложения и показать ответ.
2. Вызовите настоящее событие в тестовом режиме отправителя. У Stripe для этого есть песочница и тестовые события из командной строки; в Битрикс24 документация предлагает проверить исходящий вебхук, изменив тестовые данные на портале.
3. Откройте таблицу принятых запросов: в ней должны быть время, тело и результат проверки подписи. Попросите приложение писать это сразу, пока приёмник настраивается. Секреты и токены в таблицу не пишите: Битрикс24, например, просит не записывать application_token в логи.
4. Сравните с журналом доставок в кабинете отправителя. У Stripe на странице получателя видно попытки доставки и время следующего повтора.
5. Отправьте запрос с неверной подписью и убедитесь, что он отклонён и в таблицу не попал.

Когда вебхук или такой способ не подходит

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

Если нужно передать данные из одного сервиса в другой без своей логики, подойдёт готовый конструктор автоматизации. В n8n, например, есть узел Webhook: по документации он создаёт адрес для приёма данных, различает тестовый и рабочий адреса и предлагает проверку Basic, Header или JWT. Сравнение с n8n — на странице Allokai как аналог n8n.

Гарантий доступности у Allokai нет: если приложение не приняло запрос, повторит ли его отправитель, решает отправитель, как видно из таблицы выше. Для большого потока событий и жёстких гарантий доставки нужен отдельный сервис с очередью.

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