Документация по вебхукам

Как принять первый вебхук, настроить ответ, пробросить запрос на localhost и работать с сервисом из скриптов. Примеры готовы к запуску, подставьте только токен своего адреса.

Быстрый старт

1. Получите адрес

Откройте ленту, и адрес приёма создастся сам, без регистрации и карты. Он выглядит так: https://hook.csap.ru/t/ВАШ_ТОКЕН. Токен адреса: последняя часть после /t/. В примерах ниже вместо ВАШ_ТОКЕН подставьте свой.

2. Отправьте запрос

Адрес принимает любой метод и любой путь после токена: /t/ВАШ_ТОКЕН/orders и /t/ВАШ_ТОКЕН/pay/callback попадут в одну ленту, путь будет виден в разборе. Без правил адрес отвечает 200. Запросы из браузера тоже проходят: сервер отвечает на CORS-preflight.

curl -X POST https://hook.csap.ru/t/ВАШ_ТОКЕН/orders \
  -H 'Content-Type: application/json' \
  -d '{"event":"order.created","order_id":10428}'

3. Смотрите ленту

Запрос появится в ленте сразу, без обновления страницы: метод, путь, заголовки, параметры, тело с подсветкой JSON, форм и XML и весь запрос в сыром HTTP-виде. Запрос можно скопировать как curl или кодом на JavaScript, TypeScript, Python, PHP, Go и Rust, а повторить командой webhooks replay в CLI. Адрес работает только по HTTPS: на http:// сервер отвечает перенаправлением 301, а большинство отправителей по нему запрос не повторяют. Адрес закреплён за браузером. Чтобы он не потерялся, создайте аккаунт: адрес и принятые запросы перейдут в него, если подтвердить почту в том же браузере.

Ответы по правилам

Правило состоит из условий и действий. Правила проверяются по порядку, отвечает первое совпавшее. Если не совпало ни одно, адрес отдаёт свой ответ по умолчанию. Ненужное правило можно выключить тумблером, настройки при этом сохранятся. Правила открываются вкладкой «Ответы» в строке адреса.

  • Условия: метод, путь, заголовок, параметр запроса, тело, поле JSON, формы или XML, IP или подсеть отправителя, подпись провайдера. Строки сравниваются на равенство, вхождение, начало, окончание или регулярным выражением. Путь поля проще всего взять в разборе запроса: кнопка «Путь» у строки дерева копирует его в нужной записи (order.id, leads[status][0][id], /order/@id).
  • Ответ: код, заголовки и тело, статические или по шаблону с подстановками из запроса.
  • Задержка: ответ через заданное число миллисекунд, чтобы проверить таймауты и повторы отправителя: до 10 секунд на бесплатном тарифе и до 30 на платных.
  • Прокси на URL: запрос уходит на ваш сервер, а его ответ возвращается отправителю.
  • Копия на URL: запрос дублируется на другой адрес без ожидания ответа.
  • Отбросить соединение: закрыть без ответа, чтобы проверить, как отправитель переживает обрыв.

Подстановки шаблона: {{ request.method }}, {{ request.path }}, {{ request.ip }}, {{ request.header.Имя }}, {{ request.query.имя }}, {{ json.поле.вложенное }}, {{ form.leads[status][0][id] }}, {{ xml./order/@id }}, {{ uuid }}, {{ now }}, {{ now.unix }}, {{ random(1,100) }}, {{ hex(32) }}. Условий и циклов в шаблоне нет, только подстановка.

шаблон тела ответа
{
  "ok": true,
  "id": "{{ uuid }}",
  "order": "{{ json.order_id }}",
  "method": "{{ request.method }}",
  "trace": "{{ request.header.X-Request-Id }}",
  "at": "{{ now }}"
}

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

Проверка подписи провайдера

В панели правил, в блоке «Проверка подписи», выберите, кто шлёт вебхуки на адрес, и вставьте секрет из его кабинета. Тогда в разборе каждого запроса появится строка «Подпись: верна», «не сошлась» или «нет данных». Её можно раскрыть и увидеть, по каким заголовкам и полям считали. Секрет хранится зашифрованным и назад не показывается.

  • ЮKassa: по IP отправителя из списка ЮKassa, секрет не нужен.
  • Т-Банк: поле Token уведомления, секрет: пароль терминала.
  • Робокасса: SignatureValue на Result URL с параметрами Shp_. Секрет: «Пароль #2», алгоритм хеша берётся из настроек магазина.
  • Telegram: заголовок X-Telegram-Bot-Api-Secret-Token. Секрет придумываете сами и передаёте параметром secret_token в setWebhook. Без него Telegram заголовок не присылает.
  • Битрикс24: поле auth[application_token] исходящего вебхука.
  • GitHub: заголовок X-Hub-Signature-256, секрет: Secret вебхука.

Итог проверки можно использовать в условии правила «Подпись провайдера»: например, отвечать 401 на каждый запрос, где подпись «НЕ верна».

Тестовые события

Если настоящего вебхука под рукой нет, нажмите «Прислать пример» над лентой или на экране пустой ленты. Примеры собраны по категориям: платежи (ЮKassa, Т-Банк, Робокасса), мессенджеры (Telegram), CRM (Битрикс24, amoCRM) и для разработчиков (GitHub). Пример приходит на ваш адрес как настоящий запрос: заголовки и тело по документации провайдера, свои номера, суммы и время. В ленте он помечен «Пример».

  • Как настоящий: считается в квоте запросов, проходит правила и туннель на localhost, копии и прокси уходят.
  • С подписью: если в блоке «Проверка подписи» задан секрет того же провайдера, пример подписан им, и строка покажет «Подпись: верна». Кнопка «Проверить: прислать пример» там же шлёт пример выбранного провайдера. ЮKassa проверяется по IP, а пример шлёт сервис, поэтому у её примера IP не проверяется.
  • Кто может: тот, кто правит правила адреса; частота ограничена.

CLI и туннель на localhost

CLI webhooks собран одним файлом под Windows, macOS и Linux. Он пробрасывает запросы с адреса приёма в сервис на вашей машине. Соединение исходящее, поэтому туннель работает за NAT, без белого IP и проброса портов. Туннель есть на всех тарифах, нужен только вход в аккаунт. Сколько сессий держать одновременно, задаёт тариф.

Установка

Установщик скачает сборку под вашу систему, сверит контрольную сумму и положит клиент в PATH. Права администратора не нужны.

curl -fsSL https://hook.csap.ru/cli/install.sh | WEBHOOKS_BASE_URL=https://hook.csap.ru sh

Вход

Команда откроет страницу кабинета с кодом. Сверьте его с терминалом и подтвердите. На сервере без браузера добавьте --no-browser. В скриптах вместо входа задайте переменную WEBHOOKS_TOKEN.

вход через браузер
webhooks login --web --server https://hook.csap.ru

Туннель

В --endpoint передают токен адреса, в --target адрес локального сервиса. Если сервис проверяет заголовок Host, подмените его --header-rewrite. Приставку пути убирает --strip-prefix, а добавляет --add-prefix. Если клиент не запущен, адрес отвечает как обычно и запрос всё равно сохраняется.

туннель на localhost
webhooks tunnel --endpoint ВАШ_ТОКЕН --target http://localhost:3000 \
    --header-rewrite Host=localhost:3000

Лента, повтор и выгрузка

лента в терминале
webhooks tail ВАШ_ТОКЕН --last 20
повторить запрос №42 на localhost
webhooks replay 42 --target http://localhost:3000
выгрузить сутки в HAR
webhooks export ВАШ_ТОКЕН --since 24h -o requests.har

Справка по любой команде: webhooks <команда> -h. Все команды, ручная загрузка сборок и обновление описаны на странице «Туннель».

API

API отвечает в JSON по адресу https://hook.csap.ru/api/v1. Для скриптов и CI создайте токен в разделе «API-токены» и передавайте его заголовком Authorization: Bearer whk_…. Токен даёт доступ только к адресам, запросам и правилам, как у CLI. Пароль, оплата и остальные настройки аккаунта доступны только из кабинета. Токен действует, пока вы его не отзовёте, если при создании не выбрали срок короче. Создание токена подтверждается кодом второго фактора, а если его нет, текущим паролем. О каждом новом токене приходит оповещение.

последние 20 запросов
curl https://hook.csap.ru/api/v1/endpoints/ВАШ_ТОКЕН/requests?limit=20 \
  -H "Authorization: Bearer $WEBHOOKS_TOKEN"
Методы API, доступные по токену
МетодПутьЧто делает
GET/api/v1/endpointsадреса приёма аккаунта
POST/api/v1/endpointsзавести новый адрес
DELETE/api/v1/endpoints/{token}удалить адрес вместе с запросами
GET/api/v1/endpoints/{token}/requestsзапросы адреса, новые первыми; limit до 200, before: курсор из next_before
GET/api/v1/endpoints/{token}/requests/{id}полный разбор запроса, тело в base64
DELETE/api/v1/endpoints/{token}/requestsочистить ленту адреса
DELETE/api/v1/endpoints/{token}/requests/{id}удалить один запрос
GET/api/v1/endpoints/{token}/exportвыгрузка истории: format=har|jsonl, from и to в RFC 3339
GET/api/v1/endpoints/{token}/streamновые запросы вживую (Server-Sent Events)
GET/api/v1/endpoints/{token}/rulesправила адреса
PUT/api/v1/endpoints/{token}/rulesсохранить правила целиком
POST/api/v1/mcpMCP-сервер для ИИ-ассистентов, см. раздел ниже

Ошибка приходит с HTTP-статусом и машинным кодом причины в поле reason; request_id назовите поддержке, по нему находится запрос в журнале. Токен вне своей области получает 403 с причиной auth.session_required.

ошибка: машинный код причины
{"reason":"auth.session_required","request_id":"…"}

MCP для ИИ-ассистентов

Сервис работает как MCP-сервер (Model Context Protocol): ИИ-ассистент в редакторе кода или в чате сам смотрит пришедшие вебхуки, ждёт следующий запрос, настраивает ответы по правилам, а через CLI ещё и пробрасывает запросы на ваш localhost и повторяет их на локальный сервис. Ассистент видит запрос целиком, поэтому, пока вы отлаживаете обработчик, переключаться в ленту и копировать тела вручную не нужно.

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

Через CLI (рекомендуем)

  • Установите CLI и выполните webhooks login. Вход идёт через браузер, токен вручную копировать не нужно.
  • В настройках MCP-клиента добавьте сервер, который запускается командой webhooks с аргументом mcp (транспорт stdio), клиент запустит его сам. Флагом --allow localhost:3000 разрешите локальный сервис для туннеля и повтора (если сервисов несколько, повторите флаг).
  • Попросите ассистента показать адреса или поднять туннель на ваш порт, и он вызовет инструменты сам.
настройка MCP-клиента: через CLI
{
  "mcpServers": {
    "webhooks": {
      "command": "webhooks",
      "args": [
        "mcp",
        "--allow",
        "localhost:3000"
      ]
    }
  }
}

Туннель и повтор идут только на эту машину: localhost, 127.0.0.1 или [::1]. Другой адрес, даже в локальной сети, отклоняется с кодом target.not_local: ассистент читает чужие вебхуки, и подсказка в теле запроса не должна превратить CLI в прокси. Кроме того, разрешены только сервисы из --allow или ключа mcp_allow конфига CLI (Docker и базы на той же машине закрыты), остальные получают target.not_allowed.

Без установки, по адресу

Для ассистентов в браузере или в облаке, которые не запускают программы на вашей машине. Инструменты те же, кроме туннеля и повтора на localhost.

  • Создайте токен: кабинет → «Настройки» → «API-токены». Токен показывается один раз, сразу скопируйте его.
  • В настройках MCP-клиента добавьте удалённый сервер с транспортом Streamable HTTP по адресу https://hook.csap.ru/api/v1/mcp и заголовком Authorization: Bearer whk_… с вашим токеном.
настройка MCP-клиента: по адресу
{
  "mcpServers": {
    "webhooks": {
      "type": "http",
      "url": "https://hook.csap.ru/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer whk_…"
      }
    }
  }
}

Инструменты

Инструменты MCP для ИИ-ассистентов
ИнструментЧто делаетГде
list_endpointsадреса приёма аккаунта с полными ссылкамивезде
create_endpointзавести новый адрес в пределах тарифавезде
list_requestsзапросы адреса, новые первыми: фильтр по методу и времени, курсор before для следующей страницывезде
get_requestразбор запроса: заголовки, параметры и тело текстом, двоичное в base64; длинное тело обрезаетсявезде
wait_for_requestдождаться следующего запроса: ответ приходит, как только запрос принят, или по истечении ожиданиявезде
get_rulesправила ответов адреса и каталог условий и действийвезде
set_rulesзаменить правила адреса целиком, с теми же проверками и лимитами, что в редакторевезде
get_recipientsполучатели копий адреса: куда уходит копия каждого подходящего запроса, сводка доставок и лимит тарифавезде
save_recipientзавести или изменить получателя копий: адрес и условия, с теми же проверками, что в кабинетевезде
delete_recipientудалить получателя копий; прошлые доставки остаются в журнале адресавезде
list_test_eventsкаталог примеров вебхуков провайдеров: платежи, мессенджеры, CRM, для разработчиковвезде
send_test_eventприслать на адрес пример вебхука провайдера как настоящий запрос: квота, правила, туннель; подписан секретом адреса, если он заданвезде
start_tunnelпробросить запросы адреса на локальный сервис (по умолчанию http://localhost:3000)только через CLI
stop_tunnelостановить туннель адреса или всетолько через CLI
tunnel_statusтуннели: цель, состояние, сколько запросов доставлено, последняя ошибкатолько через CLI
tunnel_logsпоследние доставки туннеля: метод, путь, ответ локального сервиса, время (без тел)только через CLI
replay_requestповторить запрос из ленты на локальный сервис, при желании поменяв метод, путь, заголовки или телотолько через CLI

Адрес в инструментах задаётся токеном или ссылкой приёма целиком. Отказ приходит результатом инструмента с машинным кодом причины в поле reason, как в API: например, endpoint.not_found или rules.limit.reached. Ассистент видит причину и может поправить запрос. Частота вызовов ограничена.

Ассистент получает те же права, что и CLI: адреса, запросы и правила; пароль, оплата и настройки аккаунта ему недоступны, а сессия кабинета MCP-сервер не открывает. Участник команды с ролью наблюдателя смотрит, но не меняет правила. Чтобы закрыть доступ, отзовите токен на странице «API-токены».

Лимиты и тарифы

Тариф задаёт число адресов, срок хранения запросов, объём запросов за период, размер тела и доступ к туннелю. Бесплатный тариф работает без карты, адрес приёма доступен и без регистрации. Актуальные цифры есть на странице «Тарифы», расход по своему аккаунту виден в разделе «Тариф» настроек.

Вопросы и поддержка

Ответы о регистрации, хранении данных и оплате собраны в разделе «Вопросы и ответы». Если ответа там нет, напишите в поддержку из кабинета или с сайта, регистрация не нужна.

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

Cookie и Яндекс Метрика

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