Yandex Metrika

Облачный inbox webhook

Описание

Общее описание функционала

Облачный webhook inbox — постоянный публичный HTTPS-адрес для приёма вебхуков от внешних провайдеров (платёжные системы, CRM, мессенджеры и т.д.) без обязательного подключения локального клиента туннеля. Каждый inbox привязан к вашему аккаунту, имеет собственный URL и режим доставки: только сохранение с подтверждением провайдеру, пересылка на локальный сервис через подключённый клиент или пересылка на внешний HTTPS-эндпоинт (при наличии соответствующей опции тарифа).

Входящие запросы фиксируются в инспекторе HTTP-трафика с меткой webhook inbox. При сбое доставки провайдер по-прежнему получает успешное подтверждение (HTTP 200), чтобы избежать лавины повторных отправок; детали ошибки видны вам в инспекторе.

Функция доступна на тарифах с возможностью webhook-inbox. Количество inbox на аккаунт ограничено лимитом тарифа. Пересылка на удалённый HTTPS-URL требует дополнительной опции webhook-inbox-remote-forward.

Как пользователь может использовать

  • Разработчик нажимает Создать endpoint, получает публичный адрес без запущенного локального клиента и просматривает тестовые вебхуки в инспекторе.
  • Интегратор даёт провайдеру стабильный URL inbox в режиме «только хранение», пока бэкенд ещё не готов к приёму трафика.
  • Команда с подключённым клиентом туннеля пересылает вебхуки на 127.0.0.1:3000 и видит реальный HTTP-код ответа локального сервиса.
  • Пользователь с опцией удалённой пересылки направляет вебхуки на staging-сервер по HTTPS без постоянного локального туннеля.
  • QA ставит доставку на паузу, чтобы накопить события в инспекторе, не беспокоя downstream-сервис.
  • Владелец аккаунта меняет режим или адрес назначения через API или дашборд — публичный URL inbox при этом не меняется.
  • Оператор копирует public_url из раздела Туннели → Webhook inbox и вставляет его в настройки провайдера.
  • Пользователь сравнивает повторные доставки через повтор запроса (Replay) после исправления обработчика на локальной стороне.
  • Разработчик проверяет подпись или заголовки провайдера на сохранённых событиях в инспекторе до включения пересылки.
  • Команда ограничена одним inbox на бесплатном тарифе — создаёт новый только после удаления старого туннеля или смены плана с большим лимитом.
  • Владелец больше не использует endpoint и на странице /dashboard/webhook-inbox выбирает его, нажимает Удалить endpoint и подтверждает необратимое удаление. После подтверждения endpoint исчезает из списка, а его публичный URL перестаёт принимать webhook-запросы.

Как это реализовано в сервисе

1. Вы создаёте inbox в личном кабинете или через API POST /api/webhook-inboxes. Сервис выдаёт постоянный публичный URL и сохраняет настройки режима.

2. Провайдер отправляет HTTP-запрос (любой метод и путь) на этот URL. Запрос не требует входа на платформу.

3. Сервис распознаёт трафик как inbox, записывает событие в инспектор (тело, заголовки, метаданные) и в зависимости от режима:

  • Только хранение — отвечает провайдеру HTTP 200;
  • Локальная пересылка — при подключённом клиенте передаёт запрос на указанный локальный адрес и возвращает провайдеру код ответа upstream; если клиент недоступен — сохраняет событие и отвечает HTTP 200;
  • HTTPS пересылка — при наличии опции тарифа отправляет запрос на настроенный HTTPS-URL и при успехе возвращает провайдеру код ответа удалённого сервиса; при ошибке доставки — HTTP 200 и запись об ошибке в инспекторе.

4. Флаг пауза доставки останавливает пересылку, но приём и запись в инспектор продолжаются; провайдер по-прежнему получает HTTP 200.

5. Изменения режима, адреса назначения и паузы применяются через PATCH /api/webhook-inboxes или кнопки в дашборде; публичный URL остаётся прежним.

6. Когда endpoint больше не нужен, его можно удалить в дашборде. После подтверждения действие нельзя отменить: endpoint удаляется из списка, а публичный URL навсегда перестаёт принимать webhook-запросы. Дашборд показывает подтверждение успешного удаления.

Подробности API — в справочнике API. Коды ошибок — в справочнике ошибок. Ограничения — в известных ограничениях.

Справочник API

Обзор

Управление облачными webhook inbox выполняется через REST API под префиксом /api/webhook-inboxes. Все методы требуют авторизованной сессии (кука) или эквивалентной аутентификации дашборда.

Приём вебхуков от внешних провайдеров идёт на публичный URL inbox (public_url из ответа API) — без авторизации, любым HTTP-методом и с любым путём после хоста.

| Метод | Путь | Назначение |

| --- | --- | --- |

| GET | /api/webhook-inboxes | Список inbox текущего пользователя |

| POST | /api/webhook-inboxes | Создать inbox |

| PATCH | /api/webhook-inboxes?id=<tunnel_id> | Изменить режим, назначение или паузу доставки |

Другие HTTP-методы на /api/webhook-inboxes возвращают 405 Method Not Allowed.

Удаление endpoint относится к общему жизненному циклу туннеля, а не к этому набору методов.

---

GET /api/webhook-inboxes

Список всех inbox, принадлежащих авторизованному пользователю.

Успешный ответ 200

Тело JSON:

| Поле | Тип | Описание |

| --- | --- | --- |

| inboxes | массив | Список объектов inbox (может быть пустым) |

Каждый элемент массива inboxes:

| Поле | Тип | Описание |

| --- | --- | --- |

| tunnel_id | строка | Идентификатор inbox (используется в PATCH ?id=) |

| public_url | строка | Публичный HTTPS-URL для провайдера |

| mode | строка | store_only, forward_local или forward_remote |

| remote_forward_url | строка | HTTPS-URL назначения (для forward_remote; иначе пусто) |

| target_addr | строка | Локальный адрес назначения (для forward_local; иначе служебное значение) |

| delivery_paused | boolean | true — пересылка отключена, приём и запись в инспектор продолжаются |

| created_at | строка (RFC3339) | Время создания |

| updated_at | строка (RFC3339) | Время последнего изменения |

---

POST /api/webhook-inboxes

Создаёт новый inbox и выдаёт публичный URL.

Требуется возможность тарифа webhook-inbox и свободная квота max_webhook_inboxes.

Тело запроса (JSON)

| Поле | Обязательность | Описание |

| --- | --- | --- |

| mode | необязательно | Режим доставки. По умолчанию store_only. Допустимые значения: store_only, forward_local, forward_remote |

| target_addr | необязательно | Для forward_local: адрес локального сервиса, например 127.0.0.1:3000 |

| remote_forward_url | обязательно для forward_remote | Полный HTTPS-URL внешнего эндпоинта, например https://api.example.com/hooks |

Для режима forward_remote требуется опция тарифа webhook-inbox-remote-forward. URL должен использовать схему HTTPS; адреса localhost, частных и служебных сетей отклоняются при создании.

Успешный ответ 201 Created

Тело — один объект inbox (те же поля, что в списке выше).

---

PATCH /api/webhook-inboxes?id=<tunnel_id>

Частичное обновление существующего inbox. Параметр id в query обязателен и равен tunnel_id.

Публичный URL (public_url) не меняется при обновлении.

Тело запроса (JSON)

Все поля необязательны; передаются только изменяемые:

| Поле | Описание |

| --- | --- |

| mode | Новый режим: store_only, forward_local, forward_remote |

| target_addr | Новый локальный адрес для forward_local |

| remote_forward_url | Новый HTTPS-URL для forward_remote |

| delivery_paused | true — приостановить пересылку; false — возобновить |

Те же правила тарифа и валидации HTTPS-URL, что при создании, применяются при смене режима или remote_forward_url.

Успешный ответ 200

Тело — обновлённый объект inbox.

---

DELETE /api/tunnels?id=<tunnel_id>

Удаляет endpoint через общий API жизненного цикла туннелей. Используйте tunnel_id из списка inbox. После успешного удаления его публичный URL навсегда перестаёт принимать webhook-запросы, а endpoint исчезает из списка.

Успешный ответ 204 No Content

Тело ответа отсутствует.

Для работы в интерфейсе откройте /dashboard/webhook-inbox, выберите endpoint, нажмите Удалить endpoint и подтвердите действие. Удаление необратимо.

DELETE /api/webhook-inboxes не поддерживается.

---

Публичный приём вебхуков (public_url)

Внешний провайдер отправляет запросы на public_url с любым путём и query, например:

POST https://<ваш-поддомен>/hooks/payment

Авторизация на платформе не требуется.

Поведение ответа провайдеру

| Режим | Успешная доставка | Сбой доставки или пауза |

| --- | --- | --- |

| store_only | HTTP 200, пустое тело | — |

| forward_local | HTTP-код ответа локального сервиса | HTTP 200; событие в инспекторе с пометкой об ошибке доставки |

| forward_remote | HTTP-код ответа удалённого HTTPS-сервиса (безопасные заголовки ответа могут быть переданы провайдеру) | HTTP 200; событие в инспекторе с пометкой об ошибке доставки |

При delivery_paused: true пересылка не выполняется; провайдер получает HTTP 200, событие сохраняется в инспекторе.

Если возможность webhook-inbox снята с тарифа владельца, публичный URL возвращает 404 Not Found.

События помечаются в инспекторе тегом webhook-inbox. Подробнее о просмотре — в документации инспектора HTTP-трафика.

---

Дашборд

На странице /dashboard/webhook-inbox (видна при наличии возможности webhook-inbox):

  • Создать inbox — выбор режима и полей назначения;
  • Копировать / открыть public_url;
  • Пауза доставки / Возобновить доставку.
  • Удалить endpoint — выбрать endpoint, подтвердить необратимое удаление и получить подтверждение об успехе.

Подписи режимов в интерфейсе: Только хранение, Локальная пересылка, HTTPS пересылка.

Ошибки

401 Unauthorized

Когда: запрос к /api/webhook-inboxes без действующей сессии или с недействительными учётными данными.

Что делать: войдите в личный кабинет или передайте корректную авторизацию, как для остальных API дашборда.

---

403 Forbidden — заблокированный аккаунт

Когда: попытка создать inbox при заблокированном аккаунте (POST /api/webhook-inboxes).

Тело ответа (JSON): code: "user_suspended", сообщение «Аккаунт заблокирован».

Что делать: обратитесь в поддержку для разблокировки аккаунта.

---

403 Forbidden — нет возможности на тарифе

Когда:

  • создание или изменение inbox без возможности webhook-inbox на тарифе;
  • создание или переключение в режим forward_remote без опции webhook-inbox-remote-forward;
  • превышена квота max_webhook_inboxes при создании нового inbox.

Текст ответа: содержит forbidden и имя недоступной возможности или квоты (например feature webhook-inbox, feature webhook-inbox-remote-forward, quota max_webhook_inboxes).

Что делать: проверьте тариф и лимиты в разделе оплаты или обновите план. Удалите неиспользуемый inbox, если исчерпана квота количества.

---

400 Bad Request — некорректное тело

Когда: JSON в теле запроса не разбирается.

Текст ответа: invalid body.

Что делать: проверьте синтаксис JSON и заголовок Content-Type: application/json.

---

400 Bad Request — обязательный параметр

Когда: PATCH /api/webhook-inboxes без query-параметра id.

Текст ответа: id required.

Что делать: добавьте ?id=<tunnel_id> к URL.

---

400 Bad Request — недопустимый режим

Когда: в mode передано значение вне списка store_only, forward_local, forward_remote.

Текст ответа: invalid webhook inbox mode.

Что делать: используйте одно из допустимых значений режима.

---

400 Bad Request — недопустимый URL удалённой пересылки

Когда: для forward_remote указан URL не по HTTPS, адрес localhost, частной сети или иной запрещённый адрес.

Текст ответа: invalid remote forward URL.

Что делать: укажите публичный HTTPS-URL без частных IP и localhost. Если hostname указывает на частный адрес при фактическом соединении, доставка будет заблокирована; провайдер получит HTTP 200, а ошибка отобразится в инспекторе.

---

404 Not Found — inbox не найден

Когда:

  • PATCH для чужого или несуществующего tunnel_id;
  • внешний запрос на public_url inbox, если возможность webhook-inbox снята с тарифа владельца или запись inbox отсутствует.

Текст ответа (API): not found.

Что делать: проверьте tunnel_id и владельца inbox. Для публичного URL убедитесь, что inbox активен и тариф владельца включает функцию.

---

405 Method Not Allowed

Когда: на /api/webhook-inboxes вызван метод, отличный от GET, POST, PATCH (например DELETE).

Что делать: не отправляйте DELETE /api/webhook-inboxes: этот метод не поддерживается. Чтобы удалить endpoint, выберите его на /dashboard/webhook-inbox, нажмите Удалить endpoint и подтвердите действие. Для интеграции используйте общий API жизненного цикла туннелей: DELETE /api/tunnels?id=<tunnel_id>.

---

500 Internal Server Error / 503 Service Unavailable

Когда: внутренняя ошибка сервиса при создании, обновлении или чтении списка; сервис временно недоступен.

Что делать: повторите запрос позже. Если ошибка сохраняется — обратитесь в поддержку.

---

Ошибки доставки (видны в инспекторе, не в HTTP-ответе провайдеру)

Когда: пересылка на локальный клиент или удалённый HTTPS-эндпоинт не удалась (клиент отключён, сеть, таймаут, отказ upstream, отсутствие опции удалённой пересылки после смены тарифа, пауза доставки с пересылкой и т.д.).

Поведение для провайдера: HTTP 200 (подтверждение приёма), чтобы провайдер не повторял отправку бесконечно.

Поведение для вас: событие в инспекторе HTTP-трафика с тегами webhook-inbox и при необходимости delivery_error или capture_error; в заметках события — текст причины (например «локальный клиент не подключён»).

Что делать: проверьте подключение клиента, URL назначения, опцию тарифа, снимите паузу доставки; при необходимости повторите обработку через Replay.

Ограничения

  • Подтверждение провайдеру при сбое доставки. В режимах с пересылкой при недоступности назначения, паузе доставки или отсутствии опции удалённой пересылки внешний провайдер всё равно получает HTTP 200. Это сделано намеренно, чтобы остановить повторные отправки со стороны провайдера. Факт сбоя смотрите в инспекторе трафика.
  • Режим «только хранение». Провайдер всегда получает HTTP 200 с пустым телом; код ответа вашего приложения не формируется.
  • Локальная пересылка требует клиента. Без подключённого клиента туннеля запрос сохраняется в инспекторе, пересылка не выполняется, провайдер получает HTTP 200.
  • Удалённая пересылка — только HTTPS. HTTP-URL, localhost, частные и служебные адреса отклоняются при настройке; hostname, резолвящийся в частный IP при соединении, блокируется при доставке.
  • Опция удалённой пересылки. Режим forward_remote и поле remote_forward_url доступны только с опцией тарифа webhook-inbox-remote-forward. После снятия опции существующий inbox в этом режиме продолжает принимать вебхуки, но пересылка не выполняется до восстановления опции или смены режима.
  • Квота количества inbox. Лимит max_webhook_inboxes задаётся тарифом (на бесплатном плане по умолчанию — один inbox). Превышение блокирует только создание новых; существующие продолжают работать.
  • Публичный URL неизменен. Смена режима, адреса назначения или паузы не меняет выданный public_url; провайдеру не нужно обновлять endpoint.
  • Удаление необратимо. Endpoint можно удалить в /dashboard/webhook-inbox: выберите его, нажмите Удалить endpoint и подтвердите действие. После этого endpoint исчезает из списка, а его публичный URL навсегда перестаёт принимать webhook-запросы. Для интеграций доступен общий API жизненного цикла туннелей DELETE /api/tunnels?id=<tunnel_id>; отдельный DELETE /api/webhook-inboxes не поддерживается.
  • Трафик inbox и лимиты тарифа. Входящие запросы на публичный URL inbox не расходуют те же лимиты HTTP RPM и исходящего трафика, что обычный прокси-туннель; это не отменяет общие правила тарифа для остального трафика аккаунта.
  • Гостевые и закрытые туннели. Публичный URL inbox доступен внешним провайдерам без входа на платформу и не блокируется теми же правилами гостевого доступа, что приватные туннели.
  • Захват в инспекторе. Размер и полнота тела запроса зависят от настроек инспектора HTTP-трафика и тарифа; при ошибке подготовки захвата провайдер всё равно получает HTTP 200, в событии может быть тег capture_error.
  • Заголовки при удалённой пересылке. На внешний HTTPS-эндпоинт не пересылаются служебные hop-by-hop заголовки; в ответ провайдеру из upstream передаётся ограниченный набор безопасных заголовков.
  • Снятие возможности с тарифа. Если у владельца inbox больше нет webhook-inbox, публичный URL отвечает 404 Not Found; API создания и изменения также возвращает отказ.
  • Панель дашборда. Секция Webhook inbox скрыта, если возможность webhook-inbox недоступна на тарифе, даже если старые записи существуют в системе.

Дополнения

Endpoint setup and health

Общее описание функционала

Дополнение «Настройка и состояние endpoint» расширяет облачный webhook inbox инструментами для быстрого создания endpoint, диагностики доставки и пошаговой настройки у провайдера. Доступно на тарифах с возможностью webhook-inbox вместе с родительской функцией; отдельной опции тарифа для дополнения нет.

В личном кабинете, в секции Webhook endpoints, доступны два сценария создания. Создать endpoint выдаёт публичный адрес и позволяет при необходимости указать название, описание и путь. Отдельная возможность Подключить localhost, когда она доступна, настраивает пересылку в локальное приложение через клиент туннеля. После создания отображаются сведения о назначении, публичном webhook URL, состоянии туннеля и последней активности.

Панель Состояние endpoint показывает назначение, локальный URL (для локальной пересылки), метку статуса и кнопки Проверить соединение и Тестовый POST. Чеклист настройки — десять универсальных шагов (без привязки к одному провайдеру) с счётчиком прогресса; отметки сохраняются в браузере для каждого endpoint.

Статусы endpoint в списке и в панели здоровья сопоставляются с полем API endpoint_status и отображаются на русском: Активен, Запуск, Ожидание локального клиента, Локальный сервер недоступен, Назначение не отвечает, Остановлен, Истёк, Ограничен планом.

Как пользователь может использовать

  • Разработчик нажимает Создать endpoint, оставляет необязательные поля без изменений и сразу отправляет пробные вебхуки в инспектор.
  • Интегратор через то же действие задаёт название, описание и путь (например /webhooks/stripe), копирует полный public_webhook_url из чеклиста и вставляет в кабинет провайдера.
  • Команда с локальным приложением создаёт endpoint через Подключить localhost, указывает 127.0.0.1:3000, подключает клиент туннеля и следит за статусом Ожидание локального клиента → Активен.
  • Пользователь открывает панель Состояние endpoint, запускает Проверить соединение и видит, доступен ли публичный URL и (для локальной пересылки) подключён ли клиент и слушает ли порт приложения.
  • QA нажимает Тестовый POST, чтобы отправить пробный POST на публичный URL и убедиться, что ingress принимает тело (событие может появиться в инспекторе).
  • Оператор проходит Чеклист настройки (10 шагов), отмечает выполненные пункты и по кнопке Открыть инспектор переходит к просмотру входящих событий.
  • Владелец аккаунта создаёт inbox через API с полем create_intent (test_url, connect_localhost, webhook_endpoint) и читает обогащённый ответ с destination, public_webhook_url и endpoint_status.
  • Пользователь ставит доставку на паузу и видит статус Остановлен в списке и в деталях.
  • Пользователь с истёкшим по плану endpoint видит Истёк и поле expires_at в API.
  • При снятии возможности webhook-inbox с тарифа статус Ограничен планом подсказывает, что функция недоступна на текущем плане.

Как это реализовано в сервисе

1. Вы создаёте endpoint в дашборде (один из трёх сценариев) или через POST /api/webhook-inboxes с create_intent. Сервис подбирает режим доставки (только хранение или локальная пересылка), выдаёт публичный базовый URL и при необходимости сохраняет имя, описание и путь webhook.

2. При запросе детали (GET /api/webhook-inboxes?id=) или списка сервис объединяет настройки inbox с состоянием туннеля: назначение, полный публичный webhook URL, срок действия, последняя активность, признаки подключения клиента и доступности локального порта, а также вычисленный endpoint_status.

3. Проверка соединения (POST /api/webhook-inboxes/connection-check) выполняет диагностику: для локальной пересылки — проверяет сессию клиента и TCP-доступность целевого адреса; для всех режимов — пробный HTTP-запрос к публичному webhook URL (HEAD по умолчанию; POST при test_request=true). Результат возвращается структурированно; статус endpoint пересчитывается по итогам проверки.

4. Интерфейс отображает те же поля, что API: бейджи статуса, панель здоровья и чеклист. Прогресс чеклиста хранится только в браузере пользователя и не синхронизируется между устройствами.

5. Базовое поведение приёма и пересылки вебхуков описано в документации webhook inbox. Контракт полей и проверки — в справочнике API. Ошибки — в справочнике ошибок. Ограничения — в известных ограничениях.

Обзор

Дополнение «Настройка и состояние endpoint» расширяет REST API webhook inbox обогащёнными полями в ответах, сценариями создания через create_intent, детальным чтением одного inbox и проверкой соединения. Все методы требуют авторизованной сессии, как и остальные вызовы /api/webhook-inboxes.

| Метод | Путь | Назначение |

| --- | --- | --- |

| GET | /api/webhook-inboxes?id=<tunnel_id> | Деталь одного inbox с полями состояния endpoint |

| POST | /api/webhook-inboxes/connection-check?id=<tunnel_id> | Диагностика локального и публичного соединения |

| POST | /api/webhook-inboxes | Создание с опциональным create_intent и метаданными |

Список GET /api/webhook-inboxes (без id) возвращает те же обогащённые поля в каждом элементе массива inboxes, что и детальный ответ.

---

Обогащённые поля inbox

Помимо полей базового webhook inbox, в ответах детали и списка могут присутствовать:

| Поле | Тип | Описание |

| --- | --- | --- |

| name | строка | Отображаемое имя endpoint (по умолчанию — хост публичного URL) |

| description | строка | Краткое описание (для сценария webhook_endpoint) |

| webhook_path | строка | Путь webhook относительно public_url, по умолчанию / |

| create_intent | строка | Сценарий создания: test_url, connect_localhost, webhook_endpoint |

| destination | строка | Человекочитаемое назначение: Cloud storage only (только хранение), адрес host:port (локальная пересылка) или HTTPS-URL (удалённая пересылка) |

| local_url | строка | http://… для локального адреса; пусто для режима только хранения |

| public_webhook_url | строка | Полный публичный URL с учётом webhook_path |

| endpoint_status | строка | Состояние endpoint (см. список ниже) |

| tunnel_status | строка | Состояние туннеля (например активен, на паузе, истёк) |

| client_connected | boolean | Подключён ли клиент туннеля (актуально для forward_local) |

| target_reachable | boolean | Принимает ли TCP-соединения локальный адрес назначения |

| expires_at | строка (RFC3339) | Срок действия endpoint по тарифу, если задан |

| last_activity_at | строка (RFC3339) | Время последней активности туннеля |

Значения endpoint_status

| Значение API | Подпись в дашборде |

| --- | --- |

| active | Активен |

| starting | Запуск |

| waiting_for_local_connection | Ожидание локального клиента |

| local_server_unavailable | Локальный сервер недоступен |

| destination_not_responding | Назначение не отвечает |

| stopped | Остановлен |

| expired | Истёк |

| limited_by_plan | Ограничен планом |

---

GET /api/webhook-inboxes?id=<tunnel_id>

Возвращает один обогащённый объект inbox для tunnel_id, принадлежащего текущему пользователю.

Query

| Параметр | Обязательность | Описание |

| --- | --- | --- |

| id | обязателен | Идентификатор inbox (tunnel_id) |

Успешный ответ 200

Тело — объект inbox со всеми полями из списка выше и базовыми полями (tunnel_id, public_url, mode, delivery_paused, created_at, updated_at и т.д.).

---

POST /api/webhook-inboxes

Создаёт inbox. Поведение базового API сохраняется; дополнение добавляет сценарии через create_intent и метаданные.

Дополнительные поля тела (JSON)

| Поле | Обязательность | Описание |

| --- | --- | --- |

| create_intent | необязательно | Сценарий создания (см. ниже). Если не указан, эквивалентен webhook_endpoint для режима только хранения |

| name | необязательно | Имя endpoint (имеет смысл при webhook_endpoint) |

| description | необязательно | Краткое описание |

| webhook_path | необязательно | Путь webhook, например /webhooks/stripe. Для test_url и connect_localhost обычно не задаётся — используется / |

Поля mode, target_addr, remote_forward_url по-прежнему можно передать явно; при указании create_intent режим выводится из сценария.

Сценарии create_intent

| Значение | Режим доставки | Поведение |

| --- | --- | --- |

| test_url | store_only | Публичный URL без локального сервера; путь по умолчанию / |

| connect_localhost | forward_local | Требуется target_addr (например 127.0.0.1:3000); пересылка через клиент туннеля |

| webhook_endpoint | store_only | Сохраняются name, description, webhook_path; полный URL = public_url + путь |

Успешный ответ 201 Created

Тело — обогащённый объект inbox (те же поля, что у GET с id), включая create_intent, public_webhook_url и endpoint_status.

---

POST /api/webhook-inboxes/connection-check?id=<tunnel_id>

Выполняет диагностику соединения для указанного inbox. Тело запроса пустое ({}).

Query

| Параметр | Обязательность | Описание |

| --- | --- | --- |

| id | обязателен | tunnel_id inbox |

| test_request | необязательно | true — публичная проверка выполняется методом POST вместо HEAD; в ответе optional_test_sent: true |

Другие HTTP-методы на этом пути возвращают 405 Method Not Allowed.

Успешный ответ 200

| Поле | Тип | Описание |

| --- | --- | --- |

| checked_at | строка (RFC3339) | Время проверки |

| endpoint_status | строка | Статус после проверки (список выше) |

| last_activity_at | строка (RFC3339) | Последняя активность туннеля, если известна |

| optional_test_sent | boolean | true, если выполнялся POST (test_request=true) |

| local | объект | Результат локальной диагностики |

| public | объект | Результат проверки публичного webhook URL |

Объект local:

| Поле | Описание |

| --- | --- |

| applicable | true для режима forward_local; иначе false и остальные поля неактуальны |

| client_connected | Подключён ли клиент туннеля |

| target_reachable | Доступен ли TCP на target_addr |

| target_addr | Проверяемый адрес |

| message | Пояснение при проблеме (например клиент не подключён, порт не слушает) |

Объект public:

| Поле | Описание |

| --- | --- |

| checked | Выполнялась ли проверка публичного URL |

| reachable | true, если HTTP-ответ успешен (код 1–499) |

| status_code | Код HTTP-ответа пробы |

| url | Проверяемый public_webhook_url |

| message | Пояснение при ошибке сети или статусе ≥500 |

---

Дашборд

На странице Туннели, секция Webhook endpoints:

  • кнопки Тестовый URL, Подключить localhost, Webhook endpoint — соответствуют create_intent;
  • в списке — бейдж статуса по endpoint_status;
  • при выборе inbox — Состояние endpoint, Чеклист настройки (10 шагов, счётчик N/10).

Подробнее о сценариях использования — в описании дополнения.

401 Unauthorized

Когда: вызов GET /api/webhook-inboxes?id=…, POST /api/webhook-inboxes/connection-check или создание с create_intent без действующей сессии.

Что делать: войдите в личный кабинет или передайте корректную авторизацию, как для остальных API дашборда.

---

400 Bad Request — не указан идентификатор inbox

Когда:

  • GET /api/webhook-inboxes с единственной целью получить деталь, но без query-параметра id (для детали параметр обязателен);
  • POST /api/webhook-inboxes/connection-check без id в query.

Текст ответа: сообщение о том, что требуется идентификатор туннеля (id required).

Что делать: добавьте ?id=<tunnel_id> к URL.

---

400 Bad Request — недопустимый сценарий создания

Когда: в теле POST /api/webhook-inboxes передано неизвестное значение create_intent (не test_url, connect_localhost, webhook_endpoint).

Текст ответа: указывает на недопустимый сценарий создания (invalid create intent).

Что делать: используйте одно из трёх допустимых значений или опустите поле и задайте mode вручную по базовому API webhook inbox.

---

400 Bad Request — некорректное тело

Когда: JSON в теле запроса не разбирается.

Текст ответа: invalid body.

Что делать: проверьте синтаксис JSON и заголовок Content-Type: application/json.

---

405 Method Not Allowed — проверка соединения

Когда: на /api/webhook-inboxes/connection-check вызван метод, отличный от POST (например GET).

Что делать: используйте только POST с параметром id в query.

---

403 Forbidden — нет возможности или квоты

Когда: создание inbox без возможности webhook-inbox на тарифе или превышена квота max_webhook_inboxes.

Что делать: см. справочник ошибок webhook inbox. В деталях существующего inbox endpoint_status может быть limited_by_plan (Ограничен планом).

---

404 Not Found — inbox не найден

Когда: GET с id, connection-check или PATCH для чужого или несуществующего tunnel_id.

Текст ответа (API): not found.

Что делать: проверьте tunnel_id и владельца inbox.

---

500 Internal Server Error / 503 Service Unavailable

Когда: внутренняя ошибка при чтении детали, проверке соединения или создании с create_intent; сервис временно недоступен.

Что делать: повторите запрос позже. Если ошибка сохраняется — обратитесь в поддержку.

---

Диагностика без отдельного HTTP-кода ошибки

Когда: POST /api/webhook-inboxes/connection-check завершился с HTTP 200, но в теле public.reachable: false или local.client_connected: false.

Поведение: это не сбой API — сервис вернул результат проверки. Поле endpoint_status отражает выявленное состояние (например waiting_for_local_connection, local_server_unavailable, destination_not_responding).

Что делать: следуйте подсказкам в local.message и public.message; подключите клиент туннеля, запустите локальное приложение, проверьте публичный URL и настройки провайдера. Подробнее — в известных ограничениях.

---

Ошибки базового webhook inbox

Создание без create_intent, смена режима, пауза доставки и публичный приём вебхуков используют те же коды, что родительская функция — см. справочник ошибок webhook inbox.

Ограничения

  • Сценарий create_intent только при создании. Поле create_intent задаётся в POST /api/webhook-inboxes и сохраняется для отображения; сменить сценарий после создания нельзя — используйте PATCH для режима, адреса и метаданных по базовому API.
  • Статус «Запуск». В течение примерно 30 секунд после создания forward_local inbox без подключённого клиента API и дашборд могут показывать starting (Запуск) вместо Ожидание локального клиента.
  • Проверка соединения — моментальный снимок. Результат connection-check отражает состояние на момент запроса; TCP-проба локального порта кратковременна, публичная проба — HTTP HEAD или POST с сервиса. Сеть провайдера и ваш браузер могут видеть URL иначе, чем внутренняя проверка.
  • Публичная проба с платформы. Доступность public_webhook_url проверяется запросом от инфраструктуры сервиса. Локальные или корпоративные ограничения на стороне провайдера эта проверка не моделирует.
  • Тестовый POST. Кнопка Тестовый POST и параметр test_request=true отправляют пустой POST с заголовком Content-Type: application/json. Для inbox в режиме только хранения событие может появиться в инспекторе; на локальную пересылку влияет только если клиент и приложение готовы принять трафик.
  • Поле destination в API на английском. Значения вроде Cloud storage only приходят в JSON API; в дашборде те же смыслы показаны в полях Назначение на русском или в виде адреса.
  • Чеклист только в браузере. Прогресс Чеклист настройки (10 шагов, счётчик N/10) хранится в localStorage отдельно для каждого tunnel_id и браузера; другие устройства и пользователи его не видят; очистка данных сайта сбрасывает отметки.
  • Чеклист не влияет на доставку. Отметки шагов информационные; они не меняют настройки inbox, туннеля или провайдера.
  • Статус при удалённой пересылке. destination_not_responding (Назначение не отвечает) выставляется после проверки соединения или обогащения детали, когда удалённый HTTPS-назначение недоступно; для режима только хранения этот статус не применяется.
  • Список и деталь. Обогащённые поля (endpoint_status, public_webhook_url и др.) включены в список и в GET с id; для автоматизации удобнее детальный запрос, если нужны все поля одного endpoint.
  • Родительские ограничения. Квоты inbox, пауза доставки, поведение при сбое пересылки, лимиты инспектора и тарифные опции удалённой пересылки описаны в известных ограничениях webhook inbox.

Mock endpoint responses

Общее описание функционала

Аддон mock-ответов превращает облачный webhook inbox в управляемый mock-эндпоинт. Вы задаёте HTTP-статус, безопасные заголовки, тело и задержку — провайдер получает этот ответ без локального приложения. Каждый входящий запрос по-прежнему пишется в журнал трафика с пометками mock-правила или fallback.

Режим mock взаимоисключающ с хранением без доставки и с локальной/удалённой пересылкой. Правила и fallback сохраняются при смене режима.

Как пользователь может использовать

1. Включите webhook inbox и аддон mock на подходящем тарифе.

2. В карточке inbox переключите режим доставки на Mock (остальные режимы отключатся).

3. Задайте fallback (по умолчанию 200 с пустым телом) и добавьте правила: метод, точный или префиксный путь, ответ, опционально лимит использований и задержку до 10 с.

4. Примените готовый пресет (200/202/400/401/403/404/409/429/500/503) или соберите ответ вручную.

5. Отправьте webhook на публичный URL inbox — получите сконфигурированный ответ; в журнале появится событие с тегами mock.

6. При паузе доставки провайдер получает обычный ACK; правила не расходуются, событие помечается как paused, не как ошибка доставки.

Как это реализовано в сервисе

Публичный запрос к inbox в режиме mock проходит через оценку упорядоченных правил (приоритет, затем стабильный id). Первое подходящее неистекшее правило отдаёт ответ после задержки; при исчерпании использований сервис сразу переходит к следующему правилу или fallback без ожидания задержки исчерпанного правила. Ограниченные использования списываются атомарно после успешной задержки. Ответ и метаданные попадают в журнал; сбой подготовки захвата тела не меняет уже выбранный HTTP-ответ провайдеру. Ручная отправка тестового события в mock-inbox использует ту же оценку правил.

API — mock-ответы webhook inbox

Базовый путь: /api/webhook-mocks (сессия пользователя; CSRF на изменяющих методах).

| Метод | Путь | Назначение |

| --- | --- | --- |

| GET | /settings?tunnel_id= | Fallback, version, rule_count |

| PUT/PATCH | /settings | Обновить fallback с version |

| GET | /rules?tunnel_id= | Список правил |

| POST | /rules | Создать правило (preset или полный response) |

| PATCH | /rules/<id> | Обновить правило |

| DELETE | /rules/<id>?tunnel_id= | Удалить |

| POST | /rules/reorder | Транзакционный reorder + version |

Переключение режима: PATCH /api/webhook-inboxes?id= с mode: "mock" (нужны и parent inbox, и аддон mock).

Поля ответа правила/fallback: status, headers[] (name/value), тело в base64, delay_ms. Небезопасные имена заголовков (в том числе Set-Cookie, Location) отклоняются на сохранении.

Ошибки — mock-ответы webhook inbox

| HTTP | code | Когда | Что делать |

| --- | --- | --- | --- |

| 400 | invalid_request | Невалидные поля, небезопасные заголовки | Исправьте поля и повторите |

| 401 | unauthorized | Нет аутентификации | Войдите снова |

| 403 | feature_disabled | Нет webhook inbox или аддона mock | Смените тариф или дождитесь включения |

| 403 | user_suspended | Аккаунт приостановлен | Обратитесь в поддержку |

| 404 | not_found | Чужой/отсутствующий endpoint или правило | Проверьте id и владельца |

| 409 | stale_version | Устаревшая version | Перечитайте настройки и сохраните снова |

| 409 | reorder_conflict | Конфликт приоритетов при reorder | Перечитайте список правил и повторите |

| 409 | rule_quota | Больше 100 правил | Удалите лишние правила |

| 413 | body_too_large | Тело больше лимита тарифа/приложения | Уменьшите тело или включите захват тела |

| 429 | delay_concurrency | Слишком много отложенных ответов | Подождите и повторите |

| 429 | rate_limited | Превышен RPM | Снизьте частоту запросов |

| 500 | — | Неожиданная ошибка | Повторите позже или обратитесь в поддержку |

Ограничения — mock-ответы webhook inbox

  • Нет цепочки «mock, затем forward», regex/glob путей, скриптов и сетевого chaos (TCP reset, streaming).
  • Задержка ответа не больше 10 секунд.
  • Размер тела ответа не больше минимума из 256 КиБ и лимита захвата тела вашего тарифа; без права на захват тела допускается только пустое тело.
  • Не больше 100 правил на один endpoint.
  • Сопоставление пути: только exact или prefix; пустые условия = match-all.
  • В ответе нельзя задавать служебные заголовки вроде Content-Length, hop-by-hop, а также Set-Cookie и Location.
  • Аддон доступен на платных планах с webhook inbox; на Free mock по умолчанию закрыт.
  • Одновременно удерживается ограниченное число отложенных mock-ответов на владельца (лишние получают 429).