Wiki source code of 05_Вебхуки

Version 2.3 by Bimit Administrator on 13.03.2026, 16:18
Show last authors
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 * защита от поддельных запросов
57 * защита от изменения данных
58
59 //Алгоритм~://
60
61 signature = HMAC_SHA256(secret, requestBody)
62
63 где:
64
65 * secret - **токен организации**
66 * requestBody - raw JSON webhook payload
67
68 Перед вычислением подписи JSON проходит **нормализацию**, чтобы обеспечить одинаковый результат хеширования на разных платформах.
69
70 (((
71 **Нормализация JSON**
72 )))
73
74 Перед вычислением HMAC выполняются следующие правила:
75
76 1. **Поля объектов сортируются в алфавитном порядке**
77 1. Используется **компактный JSON**
78 1. **Удаляются все пробелы и переносы строк**
79 1. Используется стандартная кодировка **UTF-8**
80
81 Это гарантирует, что одинаковый payload всегда создаёт **одинаковую подпись** независимо от реализации клиента.
82 )))
83
84 (((
85 (((
86 //**Рекомендации для получателя webhook**//
87 )))
88
89 Для корректной проверки подписи рекомендуется:
90
91 1. Вычислить HMAC SHA256 либо у **raw тела запроса,** либо выполнить **такую же нормализацию JSON**
92 1. Сравнить результат с //**X-HMAC-Spec**//
93
94 Если **подпись не совпадает** - запрос следует считать **недоверенным**.
95 )))
96
97 (((
98
99
100 === //**Тело запроса**// ===
101
102 Webhook отправляется в формате **JSON**.
103
104 Пример:
105
106 {
107 "author" : "Администратор",
108 "data" : {
109 "header" : "Модель(и) отключена(ы)"
110 },
111 "event" : "model_is_off",
112 "project" : "01 checks",
113 "target" : "Администратор",
114 }
115 )))
116
117 (((
118 ==== **Поля payload** ====
119
120 |=Поле|=Тип|=Описание
121 |author|string|автор события
122 |data|object|дополнительные данные события
123 |event|string|тип события
124 |project|string|проект, в котором произошло событие
125 |target|string|пользователь, кому адресовано уведомление
126
127 === ===
128
129 === //**Ожидаемый ответ**// ===
130
131 Webhook считается **успешно доставленным**, если endpoint возвращает:
132
133 {{{ HTTP 200 OK}}}
134
135 Любой **другой HTTP код считается ошибкой доставки.**
136
137
138 === //**Повторные попытки (Retry)**// ===
139
140 Если endpoint возвращает:
141
142 * любой код ≠ **200**
143 * или происходит сетевой сбой
144 * клиент долго отвечал **(более 30 секунд)**
145
146 система автоматически повторит отправку.
147
148 Интервалы повторов:
149
150 |=Попытка|=Задержка
151 |1|30 секунд
152 |2|60 секунд
153 |3|120 секунд
154
155 После всех попыток webhook считается **недоставленным**.
156
157
158 === //**Требования к endpoint**// ===
159
160 Endpoint должен:
161
162 * принимать **HTTP POST**
163 * обрабатывать **JSON**
164 * возвращать **200 OK**, если webhook успешно обработан
165 * отвечать не дольше **30 секунд**
166 )))
167
168 (((
169
170 )))