Исходный код вики 05_Вебхуки

Версия 2.2 от Bimit Administrator на 13.03.2026, 15:48
Последние авторы
1 Webhook - это механизм автоматического оповещения вашей системы о событиях, происходящих в проектах вашей организации.
2
3 Webhook отправляется **HTTP POST запросом** на URL, указанный в настройках организации.
4
5
6 === //**Заголовки запроса**// ===
7
8 |=(% style="width: 340px;" %)Header|=(% style="width: 1151px;" %)Описание
9 |(% style="width:340px" %)Content-Type|(% style="width:1151px" %)application/json
10 |(% style="width:340px" %){{{X-Idempotency-Key}}}|(% style="width:1151px" %)Ключ идемпотентности
11 |(% style="width:340px" %){{{X-HMAC-Spec}}}|(% style="width:1151px" %)(% style="width:1225px" %)Код проверки подлинности сообщений
12
13 //**Пример**//
14
15 (((
16 Content-Type: application/json
17 )))
18
19 (((
20 X-Idempotency-Key: c0a80108-9ce6-1d7f-819c-e66fc6cc0001
21 )))
22
23 (((
24 X-HMAC-Spec:698e2329aa17f15e049694e87425f1a2a1c27271d9d472c377422d57d7c779ec
25 )))
26
27 (((
28
29
30 ==== //**X-Idempotency-Key**// ====
31
32 Содержит **уникальный идентификатор события**.
33
34 (((
35 **Зачем это нужно**
36 )))
37
38 Webhook может быть отправлен **несколько раз**, например если:
39
40 * endpoint **вернул не 200**
41 * произошёл сетевой сбой
42 * клиент долго отвечал **(более 30 секунд)**
43
44 Чтобы избежать **дублирования обработки**, сервер получателя должен:
45
46 1. сохранить X-Idempotency-Key
47 1. проверять его при каждом запросе
48 1. игнорировать уже обработанные события
49
50 ==== //**X-HMAC-Spec**// ====
51
52 Используется **для проверки подлинности webhook**. Подпись создаётся с использованием **HMAC SHA256.**
53
54 //Алгоритм~://
55
56 signature = HMAC_SHA256(secret, requestBody)
57
58 где:
59
60 * secret — токен организации
61 * requestBody — raw JSON webhook payload
62
63 Перед вычислением подписи JSON проходит **нормализацию**, чтобы обеспечить одинаковый результат хеширования на разных платформах.
64
65 (((
66 **Нормализация JSON**
67 )))
68
69 Перед вычислением HMAC выполняются следующие правила:
70
71 1. **Поля объектов сортируются в алфавитном порядке**
72 1. Используется **компактный JSON**
73 1. **Удаляются все пробелы и переносы строк**
74 1. Используется стандартная кодировка **UTF-8**
75
76 Это гарантирует, что одинаковый payload всегда создаёт **одинаковую подпись** независимо от реализации клиента.
77 )))
78
79 (((
80 (((
81 //**Рекомендации для получателя webhook**//
82 )))
83
84 Для корректной проверки подписи рекомендуется:
85
86 1. Вычислить HMAC SHA256 либо у **raw тела запроса,** либо выполнить **такую же нормализацию JSON**
87 1. Сравнить результат с //**X-HMAC-Spec**//
88
89 Если подпись не совпадает - запрос следует считать **недоверенным**.
90 )))
91
92 (((
93
94
95 === //**Тело запроса**// ===
96
97 Webhook отправляется в формате **JSON**.
98
99 Пример:
100
101 {
102 "author" : "Администратор",
103 "data" : {
104 "header" : "Модель(и) отключена(ы)"
105 },
106 "event" : "model_is_off",
107 "project" : "01 checks",
108 "target" : "Администратор",
109 }
110 )))
111
112 (((
113 ==== **Поля payload** ====
114
115 |=Поле|=Тип|=Описание
116 |author|string|автор события
117 |data|object|дополнительные данные события
118 |event|string|тип события
119 |project|string|проект, в котором произошло событие
120 |target|string|пользователь, кому адресовано уведомление
121
122 === ===
123
124 === //**Ожидаемый ответ**// ===
125
126 Webhook считается **успешно доставленным**, если endpoint возвращает:
127
128 {{{ HTTP 200 OK}}}
129
130 Любой **другой HTTP код считается ошибкой доставки.**
131
132
133 === //**Повторные попытки (Retry)**// ===
134
135 Если endpoint возвращает:
136
137 * любой код ≠ **200**
138 * или происходит сетевой сбой
139 * клиент долго отвечал **(более 30 секунд)**
140
141 система автоматически повторит отправку.
142
143 Интервалы повторов:
144
145 |=Попытка|=Задержка
146 |1|30 секунд
147 |2|60 секунд
148 |3|120 секунд
149
150 После всех попыток webhook считается **недоставленным**.
151
152
153 === //**Требования к endpoint**// ===
154
155 Endpoint должен:
156
157 * принимать **HTTP POST**
158 * обрабатывать **JSON**
159 * возвращать **200 OK**, если webhook успешно обработан
160 * отвечать не дольше **30 секунд**
161 )))
162
163 (((
164
165 )))