Вебхуки

Вебхуки отправляют push-уведомления о событиях на ваш HTTP-эндпоинт, когда на TrucklineMP что-то меняется. Настройте их в Консоли разработчика.

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

Создание вебхука

1. Откройте раздел Webhooks в Консоли разработчика.
2. Нажмите Create Webhook.
3. Введите имя, URL-адрес HTTPS-эндпоинта и выберите нужные вам события.
4. Скопируйте signing secret, когда он отобразится. Он понадобится вам для проверки доставок.

Каждый вебхук принадлежит вашему аккаунту разработчика. Вы можете создать несколько эндпоинтов для разных сред (тестовая, рабочая).

Формат доставки

TrucklineMP отправляет HTTP POST с телом в формате JSON:

{
  "event": "vtc.member_joined",
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-06-30T12:00:00.000Z",
  "data": {
    "vtcId": 42,
    "userId": "user_abc",
    "role": "Driver"
  }
}

Заголовки запроса

Заголовок	Описание
Content-Type	application/json
X-TrucklineMP-Signature	Подпись HMAC-SHA256 (sha256=<hex>)
X-TrucklineMP-Event	Тип события (например, vtc.member_joined)
X-TrucklineMP-Delivery	Уникальный ID доставки (совпадает с event_id)

Вы также можете прикрепить пользовательские заголовки в настройках вебхука. Названия чувствительных заголовков (Authorization, Cookie и подобные) удаляются из логов доставки.

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

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

expected = "sha256=" + HMAC_SHA256(secret, raw_body)

Сравните expected с заголовком X-TrucklineMP-Signature, используя сравнение за постоянное время. Отклоняйте запросы с недействительными подписями до обработки полезной нагрузки.

Пример (Node.js):

import { createHmac, timingSafeEqual } from "crypto";

function verifySignature(rawBody, signatureHeader, secret) {
  const expected = "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex");
  if (!signatureHeader || signatureHeader.length !== expected.length) return false;
  return timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expected));
}

Повторные попытки

Неудачные доставки повторяются автоматически. Задержки повторных попыток по умолчанию:

Попытка	Задержка после неудачи
1	30 секунд
2	2 минуты
3	10 минут

Доставка считается успешной, когда ваш эндпоинт возвращает HTTP 2xx. Перенаправления (3xx) рассматриваются как неудачи. Таймауты по умолчанию составляют 30 секунд на каждую попытку.

История и статус доставки видны в консоли. Используйте кнопку Send Test, чтобы инициировать событие webhook.test для вашего эндпоинта.

Каталог событий

Подписывайтесь только на те события, которые нужны вашей интеграции.

Пользователи

Событие	Описание
user.updated	Профиль пользователя был обновлен
user.banned	Пользователь был забанен
user.unbanned	Бан пользователя был снят

VTC

Событие	Описание
vtc.created	Была создана новая VTC
vtc.member_joined	Пользователь вступил в VTC
vtc.member_left	Пользователь покинул VTC
vtc.updated	Данные VTC были обновлены

Мероприятия

Событие	Описание
event.created	Было опубликовано новое мероприятие
event.updated	Мероприятие было обновлено
event.cancelled	Мероприятие было отменено
event.rsvp	Пользователь ответил на приглашение RSVP на мероприятие

Модерация

Событие	Описание
ban.issued	Был выдан бан
ban.appealed	Была подана апелляция на бан
ban.appeal_resolved	Апелляция на бан была рассмотрена

API (на уровне аккаунта)

Событие	Описание
api.rate_limit_hit	Один из ваших токенов API достиг лимита запросов
api.token_revoked	Токен API был отозван

Тестирование

Событие	Описание
webhook.test	Ручная тестовая доставка из консоли

Точные поля полезной нагрузки зависят от события. Обрабатывайте data как специфичный для события объект и игнорируйте неизвестные поля для обеспечения прямой совместимости.

Требования к эндпоинтам

• Используйте HTTPS в рабочей среде.
• Быстро отвечайте кодом 2xx. Передавайте тяжелую работу в фоновую очередь.
• Возвращайте 2xx только после того, как вы приняли полезную нагрузку. TrucklineMP не будет повторять успешные доставки.
• Не следуйте перенаправлениям на принимающей стороне. Ответы с перенаправлением приводят к ошибке доставки.

URL-адреса частных сетей и небезопасные направления блокируются платформой.

Вебхуки для объявлений VTC (отдельная функция)

Владельцы VTC могут настроить вебхуки для объявлений в Discord в своей панели управления VTC. Эти вебхуки публикуют отформатированные embed-сообщения в Discord, когда происходят события в VTC (вступления участников, заявки и подобное).

Вебхуки из Консоли разработчика работают иначе. Это HTTP-эндпоинты на уровне аккаунта для кода вашей интеграции. См. Объявления VTC для ознакомления с функцией, ориентированной на Discord.

Связанные руководства

• Обзор платформы для разработчиков
• Публичный API
• Приложения OAuth