Исходящий webhook

Webhook отправляет HTTP POST во внешнюю систему при выбранном событии. Он подходит, например, чтобы сообщить о создании записи без постоянного опроса API.

Подготовка

Владелец принимающей программы должен предоставить HTTPS-адрес и реализовать проверку подписи. Суперпользователь открывает Настройки платформы → Настройка системы → Интеграции → Отправка событий. Сервер отдельно проверяет права управления webhook; у исполнителя должны быть права читать передаваемые записи.

1. Выберите нужное событие и получателя.
2. Настройте отдельный общий секрет подписи у обеих сторон.
3. Выберите исполнителя с ограниченными правами.
4. Убедитесь, что обработчик webhook включён.
5. Проверьте учебное событие и журнал доставки, затем включайте реальный обмен.

Настройка через интерфейс

Нажмите «Добавить отправку», укажите название, назначение и HTTPS-адрес без ключей и паролей в URL, отметьте события и выберите «От чьего имени читать данные».

В «Защите сообщений» можно создать ключ подписи автоматически либо выбрать доступную ссылку на секрет. Если на сервере не настроено шифрование секретов, сначала обратитесь к сопровождающему: секреты открытым текстом не сохраняются. Новый ключ показывается один раз; сохраните его в защищённом хранилище, настройте у получателя и нажмите «Я сохранил ключ — закрыть». Не делайте скриншот этого экрана.

Сохранение не отправляет сообщение. Включение — отдельное подтверждаемое действие. При изменении можно создать новый ключ взамен прежнего; сначала согласуйте замену с получателем. Дополнительные ранее настроенные фильтры сохраняются, даже если их нет в простой форме.

В карточке списка доступны «Изменить», «Включить / Выключить», «В архив». Архивное подключение можно восстановить отдельно; обмен автоматически не возобновляется. Блок результатов показывает последние доставки из 100 записей, число попыток и HTTP-ответ. «Повторить отправку» появляется для завершившейся неудачей доставки включённого неархивного подключения. Перед повтором проверьте защиту получателя от дублей по deliveryId.

Безопасно изменить адрес или ключ

Сначала выключите отправку: изменить включённое подключение нельзя. В адресе запрещены не только пароль, но и параметры после ? и фрагмент после #; нужен чистый HTTPS endpoint. Исправьте настройки, сохраните выключенными, согласуйте ключ подписи с получателем и только затем включите.

Перед повторным включением проверьте ожидающие доставки: помимо новых событий могут продолжиться уже поставленные в очередь. Выключение или архивирование не отзывают сетевой запрос, который уже начался. В результатах «Пропущено — нет доступа к записи» не означает передачу данных: сервер намеренно не отправил недоступный объект.

Что получает внешняя система

POST /events HTTP/1.1
Host: receiver.example.invalid
Content-Type: application/json
X-ITSM-Delivery: DELIVERY_ID
X-ITSM-Timestamp: 2026-10-13T10:00:00.000Z
X-ITSM-Signature: sha256=HMAC_VALUE

{"deliveryId":"DELIVERY_ID","eventId":"EVENT_ID","eventType":"ObjectCreated","timestamp":"2026-10-13T10:00:00.000Z","data":{"objectId":"OBJECT_ID","revision":1,"object":{"id":"OBJECT_ID","values":{}}}}

Пример сокращён. Карточка читается с актуальными правами исполнителя на момент отправки. Это не исторический снимок события: запись могла измениться. Скрытые поля не отправляются.

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

Получатель сохраняет исходные байты тела до разбора JSON. Вычислите HMAC-SHA256 общим секретом от:

timestamp + "." + deliveryId + "." + rawBody

Сравните hex-результат с частью после sha256= безопасным сравнением. Проверьте допустимый возраст timestamp и сохраните deliveryId вместе с результатом обработки в устойчивом хранилище.

Не доверяйте одному заголовку

Само наличие X-ITSM-Signature не доказывает подлинность события. Нужны проверка подписи, HTTPS и защита от повторной обработки deliveryId. API-ключ NGENSIA не используется как Authorization получателя.

Повторы и ошибки

Возвращайте 2xx только после надёжного принятия. 429, 5xx и временные ошибки соединения повторяются в пределах политики попыток; другие неуспешные HTTP-коды завершают отправку. Стандартная политика — 3 попытки с увеличением задержки.

Повторная доставка возможна: обработчик получателя должен быть идемпотентным. После устранения причины ошибки используйте доступное в интерфейсе действие «Повторить отправку»; подключение должно оставаться включённым.

Связанные статьи

• Методы webhook
• Фоновые обработчики
• Выбор способа интеграции