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

Summary

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

Details

Page properties

Title

...	...	@@ -1,1 +1,1 @@
1		-05_webhook
	1	+05_Вебхуки

Content

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