Входящие вебхуки

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

Как это работает

Каждая установка с типом WEBHOOK_INBOUND или BIDIRECTIONAL получает уникальный URL вебхука. Внешний сервис отправляет POST-запросы на этот адрес — платформа принимает, проверяет подпись и обрабатывает.

Внешний сервис → POST /api/v1/webhooks/inbound/{token} → Обработка → Журнал

Управление эндпоинтом

Получить текущий эндпоинт

GET /api/v1/integrations/installations/:id/webhook-endpoint

json

{
  "id": "endpoint-uuid",
  "url": "https://snabplus.com/api/v1/webhooks/inbound/a3f1b2c4d5e6...",
  "secretMasked": "••••••••",
  "isActive": true,
  "lastReceivedAt": "2026-04-27T09:15:00.000Z",
  "receivedCount": 4821
}

Секрет для проверки подписи хранится зашифрованным и никогда не возвращается в открытом виде.

Перегенерировать эндпоинт

POST /api/v1/integrations/installations/:id/webhook-endpoint/regenerate

Инвалидирует старый токен и создаёт новый. Новый секрет возвращается один раз — сохраните его сразу.

json

{
  "url": "https://snabplus.com/api/v1/webhooks/inbound/новый-токен",
  "secretPlaintext": "a1b2c3d4e5f6...",
  "regeneratedAt": "2026-04-27T10:00:00.000Z"
}

После перегенерации обновите настройки вебхука в панели внешнего сервиса.

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

Платформа поддерживает HMAC-SHA256 верификацию входящих запросов.

Внешний сервис должен передавать:

Заголовок X-Webhook-Timestamp — Unix timestamp запроса
Заголовок X-Webhook-Signature — подпись в формате sha256=<hex>

Подпись вычисляется как:

HMAC-SHA256(secret, "{timestamp}.{rawBody}")

Если заголовки отсутствуют — запрос принимается без проверки подписи (для сервисов, которые её не поддерживают). Для защищённых сред рекомендуется использовать подпись.

Публичный эндпоинт приёма

POST /api/v1/webhooks/inbound/:token

Не требует аутентификации — доступен из интернета для внешних сервисов.

Платформа:

Находит активный эндпоинт по токену
Проверяет, что установка активна и не удалена
Проверяет HMAC-подпись (если заголовки присутствуют)
Санирует payload (редактирует поля password, secret, token и подобные)
Записывает событие в журнал
Передаёт на обработчик конкретной интеграции
Возвращает 200 OK или 202 Accepted

При неверном токене или неактивной установке — 404 Not Found.
При ошибке подписи — 401 Unauthorized.

Журнал входящих событий

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

GET /api/v1/integrations/installations/:id/logs?direction=INBOUND

Подробнее — в разделе Управление установками.

Входящие вебхуки ​

Как это работает ​

Управление эндпоинтом ​

Получить текущий эндпоинт ​

Перегенерировать эндпоинт ​

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

Публичный эндпоинт приёма ​

Журнал входящих событий ​

Рекомендации по настройке ​