Webhooks API (v1)
Исходящие вебхуки (HTTP push) для интеграций с внешними системами.
При наступлении события в TMS система сама отправляет POST-запрос на URL, указанный в настройках вебхука. В отличие от API Событий, опрашивать TMS не нужно.
Основные особенности:
- Вебхук настраивается для компании (тенанта) сотрудниками TRUCKER: указываются URL получателя, список событий (
event_slug), формат тела (jsonилиxml) и способ авторизации. На один URL в рамках компании может быть настроен только один вебхук. - Одно событие — один HTTP-запрос. Тело запроса — плоский объект, первым полем которого всегда идёт
event_slug(идентификатор события), далее — поля конкретного события. - Вебхук получает компания-получатель события: для событий по заявкам и рейсам — заказчик (грузовладелец), для событий цифровой очереди — владелец цифровой очереди. Получатель указан в описании каждого события.
- События по заявкам, рейсам и бронированиям отправляются, только если источник заказа (
ui,import,integration,api) входит в список источников, разрешённых для компании-получателя (по умолчанию — все источники). На событиеintegration_payload_processedэто ограничение не действует.
Запрос:
POST <URL вебхука> Content-Type: application/json # или application/xml для формата xml User-Agent: TMS Webhook Allow: */* Authorization: <см. «Авторизация»>
- Сообщения отправляются асинхронно, в фоне, обычно в течение нескольких минут после события.
- Сообщение считается доставленным, если получатель ответил любым кодом
2xx. Тело ответа не анализируется. - Если получатель ответил кодом не
2xxили не ответил вовсе, отправка по этому вебхуку останавливается (следующие сообщения в очереди не отправляются) и повторяется через 2 часа, начиная с недоставленного сообщения. Отправка также возобновляется при появлении нового сообщения для вебхука. Количество повторов не ограничено. - Возможна повторная доставка одного и того же сообщения, обработка на стороне получателя должна быть идемпотентной.
- В тело могут добавляться новые поля. Получатель должен игнорировать неизвестные поля.
Для вебхука настраивается один из способов:
basic_auth— заголовокAuthorization: Basic <base64(login:password)>.access_token— заголовокAuthorization: Bearer <ACCESS_TOKEN>.certificate— взаимная TLS-аутентификация (mTLS) клиентским сертификатом, заголовокAuthorizationне передаётся.
Схемы и примеры ниже приведены для формата json:
- даты — строка
YYYY-MM-DD; - дата и время — строка ISO 8601 в UTC с миллисекундами, например
2025-08-29T10:15:30.123Z; - денежные суммы — число в основных единицах валюты (рубли), например
1500.0; - отсутствующие значения передаются как
null.
Для формата xml передаются те же поля: корневой элемент — <webhook>, имена элементов совпадают с ключами JSON (подчёркивания сохраняются). Строки передаются без атрибутов, для остальных значений указывается атрибут type (integer, float, boolean, date, dateTime, array; для полей source, как правило, — symbol), для null — атрибут nil="true". Дата и время передаются без миллисекунд (2025-08-29T10:15:30Z). Элементы массива именуются в единственном числе от имени массива.
Пример:
<?xml version="1.0" encoding="UTF-8"?>
<webhook>
<event_slug>run_status_set</event_slug>
<reference_number>REF-000123</reference_number>
<executor>
<external_number>T-1234</external_number>
</executor>
<status>on_execution</status>
<registered_at type="dateTime">2025-08-29T10:15:30Z</registered_at>
<source type="symbol">driver</source>
<data>
</data>
<happened_at type="dateTime">2025-08-29T10:10:00Z</happened_at>
<happened_at_time_zone>Europe/Moscow</happened_at_time_zone>
</webhook>