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>

Коды ответов получателя

  • 2xx - Сообщение доставлено.
  • Любой другой код или отсутствие ответа - Сообщение не доставлено, отправка будет повторена.