26.06.2026 16:55

Вебхуки

Содержание

Введение

Вебхуки в REGOS - это способ доставки тех же событий во внешние системы. Каждое событие отправляется на указанный URL интеграции методом POST в формате JSON. Вебхук добавляет к событию внешний конверт доставки и токен интеграции (connected_integration_id).

Для каждого connected_integration_id в системе формируется собственный рейтинг надёжности доставки вебхуков: по статистике успешных и неуспешных отправок конкретной интеграции. Надёжные интеграции со стабильной доставкой попадают в «белый список» и получают привилегированный режим обработки (расширенное окно даунтайма, отдельную очередь повторной доставки и более щадящую стратегию ретраев). Интеграции и их URL, которые систематически не отвечают или возвращают ошибки, могут временно попадать в «чёрный список» — в этот период новые вебхуки для них не доставляются и не занимают ресурсы сервиса до истечения времени блокировки.

Единая структура события описана на странице События. Потерянные realtime/webhook-события можно восстановить методом Event/Get .

Общая структура вебхука

Вебхук отправляет событие в конверте HandleWebhook. Поля event_id, occurred_at, data.action и data.data соответствуют структуре события, описанной на странице События.

Название Тип данных Обязательность Описание
action String Обязательный Всегда "HandleWebhook"
event_id String Обязательный UUID события
occurred_at DateTime Обязательный Дата и время возникновения события в REGOS, UTC, ISO 8601
connected_integration_id String Обязательный Токен подключённой интеграции
data.action String Обязательный Тип события
data.data Object Обязательный Полезная нагрузка события

Как обрабатывать вебхуки

  1. Метод: Вебхуки отправляются методом POST.
  2. Аутентификация: Проверьте connected_integration_id для подтверждения источника.
  3. Формат ответа: Ожидается HTTP-статус 200 OK.
  4. Таймаут запроса — 3 секунды.
  5. Повторные попытки: REGOS повторяет отправку до 3 раз в случае недоступности сервера.

События, доставляемые вебхуками

Вебхуки доставляют события из общего справочника на странице События. Значение data.action в webhook-конверте совпадает с action события. Подписки подключённой интеграции определяют, какие события из общего списка будут отправлены вебхуком.

Примеры вебхука

{
  "action": "HandleWebhook",
  "event_id": "2f0f7b7a-7c43-4d91-917f-8f412ad0ab5e",
  "occurred_at": "2026-06-26T10:00:00Z",
  "connected_integration_id": "string",
  "data": {
    "action": "DocOrderDeliveryStatusSet",
    "data": {
      "id": 54321,
      "status": "Completed"
    }
  }
}