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

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

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

Интеграция с входящим webhook получает уникальный URL. Внешний сервис отправляет POST-запросы на этот адрес, а SNABZHENETS+ принимает событие, обязательно проверяет подпись, применяет активные inbound mappings и записывает результат в журнал.

Внешний сервис → webhook URL SNABZHENETS+ → mapping → бизнес-сущность / журнал

Управление URL

Получить текущий URL

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

Метод возвращает URL вебхука, статус активности, маску секрета, дату последнего события и количество полученных событий. Секрет для проверки подписи не возвращается в открытом виде.

Перегенерировать URL

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

Метод создаёт новый URL и новый секрет. Новый секрет показывается один раз — сохраните его сразу и обновите настройки вебхука во внешнем сервисе.

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

SNABZHENETS+ требует HMAC-SHA256 для проверки входящих запросов.

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

• X-Snabplus-Timestamp — время запроса;
• X-Snabplus-Signature — подпись в формате sha256=<hex>;
• X-Snabplus-Event — тип события для выбора mapping.

Для совместимости также принимается X-Timestamp.

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

{timestamp}.{rawBody}

Запросы без подписи или с устаревшим timestamp отклоняются.

Публичный адрес приёма

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

Адрес доступен из интернета для внешних сервисов и не требует пользовательской авторизации. При успешном приёме возвращается 202 Accepted. Если URL неверный, интеграция отключена или подпись не прошла проверку, запрос будет отклонён.

Inbound mappings

В консоли API/Webhooks можно создать mapping без пользовательского JavaScript. Mapping описывает:

• событие, например catalog.item.upserted;
• безопасную операцию, например catalog_item.upsert;
• JSONPath-правила source, например { "name": "$.name" };
• defaults, requiredFields, idempotencyPath, externalSource, externalIdPath.

Поддерживаемые операции v1: event.record, catalog_item.upsert, counterparty.upsert, procurement.status.

Outbound webhooks

Outbound subscriptions отправляют события SNABZHENETS+ во внешнюю систему. Payload содержит event, eventId, tenantId, entity, occurredAt, data и links. Каждый запрос подписывается:

X-Snabplus-Event: integration_api.procurement.status_changed
X-Snabplus-Event-Id: audit-log-uuid
X-Snabplus-Timestamp: 1760000000000
X-Snabplus-Signature: sha256=<hex>

Стабильный каталог v1:

• integration_api.procurement.created
• integration_api.procurement.updated
• integration_api.procurement.status_changed
• integration_api.procurement.deleted
• integration_api.catalog_item.created
• integration_api.catalog_item.updated
• integration_api.catalog_item.deleted
• integration_api.counterparty.created
• integration_api.counterparty.updated
• integration_api.counterparty.status_changed
• integration_api.counterparty.deleted
• integration_api.warehouse.created
• integration_api.warehouse.updated
• integration_api.warehouse.deleted
• integration_api.price_list.created
• integration_api.price_list.updated
• integration_api.price_list.status_changed
• integration_api.price_list.deleted
• integration_api.invoice.created
• integration_api.invoice.updated
• integration_api.invoice.status_changed
• integration_api.invoice.deleted
• integration.test_event

Сущности в исходящих событиях

Сущность	Системное имя	Какие события отправляются
Закупка	procurement	Создание, обновление, смена статуса, удаление или архивирование
Номенклатура	catalog_item	Создание, обновление, удаление или архивирование
Контрагент	counterparty	Создание, обновление, смена статуса, удаление или архивирование
Склад	warehouse	Создание, обновление, удаление или архивирование
Прайс-лист	price_list	Создание, обновление, смена статуса, удаление или архивирование
Счёт	invoice	Создание, обновление, смена статуса, удаление или архивирование
Тест интеграции	integration	Тестовое событие для проверки доставки, заголовков и подписи

Типы событий:

Тип	Когда отправляется
Создание	В SNABZHENETS+ появилась новая сущность.
Обновление	Изменились поля существующей сущности.
Смена статуса	Изменился статус сущности, и внешняя система должна отдельно отреагировать на переход.
Удаление или архивирование	Сущность стала неактивной, удалена или архивирована. Этот тип есть только у архивируемых сущностей.
Тестовое событие	Пользователь вручную проверяет webhook-подписку без изменения бизнес-данных.

Для исходящей подписки нужно выбрать хотя бы одно событие из каталога. Пустой список событий недопустим и больше не означает «все события». Тестовое integration.test_event отправляется только ручной проверкой подписки.

Подпись считается по строке {timestamp}.{rawBody}. Повторы выполняются при сетевой ошибке, 408, 429 и 5xx; каждая попытка видна в логах доставки.

Полный справочник outbound events с русскими названиями сущностей доступен в разделе Исходящие webhook-события.

Управление outbound webhooks через API

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

GET    /api/v1/integration-api/webhook
POST   /api/v1/integration-api/webhook
PUT    /api/v1/integration-api/webhook/:id
DELETE /api/v1/integration-api/webhook/:id
POST   /api/v1/integration-api/webhook/:id/test

Для чтения нужен scope webhooks.read или integration_api.read; для создания, изменения и теста — webhooks.write или integration_api.write; для отключения — webhooks.delete или integration_api.delete.

POST принимает JSON-массив. Каждый элемент создаёт отдельную подписку на одно событие и один URL:

[
  {
    "name": "ERP procurement status",
    "event": "integration_api.procurement.status_changed",
    "url": "https://erp.example.com/hooks/snabzhenets",
    "isActive": true
  }
]

Ответ создания возвращает secretPlaintext один раз. Список, изменение, отключение и тестовая доставка возвращают JSON без секрета. Подробнее: Integration API.

Webhook также можно отправить как действие автоматизации воронки. Такой запрос настраивается в Настройки → Воронка → кнопка робота на этапе, поддерживает POST в форматах JSON по умолчанию, custom JSON и application/x-www-form-urlencoded, а payload собирается визуальным списком key/value с token picker. Результат виден в журнале запусков сценария.

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

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

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

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

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

• Храните секрет вебхука в защищённом месте.
• Если секрет скомпрометирован, сразу перегенерируйте URL.
• Настройте подпись на стороне внешнего сервиса, если он её поддерживает.
• Проверяйте дату последнего события и счётчик полученных событий в карточке установки.