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

Summary

• Page properties (1 modified, 0 added, 0 removed)

Details

Page properties

Content

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