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

Last modified by Bimit Administrator on 13.03.2026, 16:18
From version 3.1
edited by Bimit Administrator
on 13.03.2026, 16:18
Change comment: There is no comment for this version
To version 1.1
edited by Bimit Administrator
on 13.03.2026, 14:14
Change comment: There is no comment for this version

Summary

Details

Page properties
Title
... ... @@ -1,1 +1,1 @@
1 -05_Вебхуки
1 +05_webhook
Content
... ... @@ -1,170 +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 -* защита от поддельных запросов
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 -)))