05_Вебхуки

Версия 2.2 от Bimit Administrator на 13.03.2026, 15:48

Webhook - это механизм автоматического оповещения вашей системы о событиях, происходящих в проектах вашей организации.

Webhook отправляется HTTP POST запросом на URL, указанный в настройках организации.

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

Header	Описание
Content-Type	application/json
X-Idempotency-Key	Ключ идемпотентности
X-HMAC-Spec	Код проверки подлинности сообщений

Пример

Content-Type: application/json

X-Idempotency-Key: c0a80108-9ce6-1d7f-819c-e66fc6cc0001

X-HMAC-Spec:698e2329aa17f15e049694e87425f1a2a1c27271d9d472c377422d57d7c779ec

X-Idempotency-Key

Содержит уникальный идентификатор события.

Зачем это нужно

Webhook может быть отправлен несколько раз, например если:

endpoint вернул не 200
произошёл сетевой сбой
клиент долго отвечал (более 30 секунд)

Чтобы избежать дублирования обработки, сервер получателя должен:

сохранить X-Idempotency-Key
проверять его при каждом запросе
игнорировать уже обработанные события

X-HMAC-Spec

Используется для проверки подлинности webhook. Подпись создаётся с использованием HMAC SHA256.

Алгоритм:

signature = HMAC_SHA256(secret, requestBody)

где:

secret — токен организации
requestBody — raw JSON webhook payload

Перед вычислением подписи JSON проходит нормализацию, чтобы обеспечить одинаковый результат хеширования на разных платформах.

Нормализация JSON

Перед вычислением HMAC выполняются следующие правила:

Поля объектов сортируются в алфавитном порядке
Используется компактный JSON
Удаляются все пробелы и переносы строк
Используется стандартная кодировка UTF-8

Это гарантирует, что одинаковый payload всегда создаёт одинаковую подпись независимо от реализации клиента.

Рекомендации для получателя webhook

Для корректной проверки подписи рекомендуется:

Вычислить HMAC SHA256 либо у raw тела запроса, либо выполнить такую же нормализацию JSON
Сравнить результат с X-HMAC-Spec

Если подпись не совпадает - запрос следует считать недоверенным.

Тело запроса

Webhook отправляется в формате JSON.

Пример:

{
  "author" : "Администратор",
  "data" : {
    "header" : "Модель(и) отключена(ы)"
  },
  "event" : "model_is_off",
  "project" : "01 checks",
  "target" : "Администратор",
}

Поля payload

Поле	Тип	Описание
author	string	автор события
data	object	дополнительные данные события
event	string	тип события
project	string	проект, в котором произошло событие
target	string	пользователь, кому адресовано уведомление

Ожидаемый ответ

Webhook считается успешно доставленным, если endpoint возвращает:

  HTTP 200 OK

Любой другой HTTP код считается ошибкой доставки.

Повторные попытки (Retry)

Если endpoint возвращает:

любой код ≠ 200
или происходит сетевой сбой
клиент долго отвечал (более 30 секунд)

система автоматически повторит отправку.

Интервалы повторов:

Попытка	Задержка
1	30 секунд
2	60 секунд
3	120 секунд

После всех попыток webhook считается недоставленным.

Требования к endpoint

Endpoint должен:

принимать HTTP POST
обрабатывать JSON
возвращать 200 OK, если webhook успешно обработан
отвечать не дольше 30 секунд