Changes for page 05_Вебхуки

Last modified by Bimit Administrator on 13.03.2026, 16:18
From version 2.2
edited by Bimit Administrator
on 13.03.2026, 15:48
Change comment: There is no comment for this version
To version 2.1
edited by Bimit Administrator
on 13.03.2026, 14:15
Change comment: There is no comment for this version

Summary

Details

Page properties
Content
... ... @@ -1,165 +1,0 @@
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 -)))