Обмін вебхуками та сповіщення між сервісами

Інтеграція, яку збирали нашвидкуруч, майже ніколи не падає гучно. Вона просто перестає щось робити: подія пішла, приймач тієї секунди перезавантажувався, повторити нікому — і про те, що клієнтові не надійшло підтвердження, ви дізнаєтеся від самого клієнта. Я роблю цей обмін нудним і передбачуваним, а це найкраще, що може статися з інтеграцією: є куди прийняти подію, є черга, є маршрути сповіщень і є журнал, який відповідає на питання «чи дійшло».

Починаю з розбору подій, а не з коду. Ми проходимо тим, що справді відбувається у ваших системах, і залишаємо те, на що варто реагувати: нове замовлення, невдала оплата, зміна статусу, підписаний документ. Для кожної події записую, хто має про неї дізнатися, як швидко і яким каналом. Зазвичай саме тут зникає половина майбутнього шуму, бо доти ніхто не питав, чи заслуговує подія на окреме повідомлення.

Тепер про надійність, і це не оздоблення кошторису. Вебхук без перевірки підпису не приймається — інакше подію може надіслати будь-хто, а підроблена коштує дорожче за пропущену. Прийняті події лягають у чергу й повторюються з дедалі більшими паузами, доки приймальна сторона мовчить. Повтори тут звичайна річ, тому кожна подія має ключ, і друга копія того самого ключа не змінює нічого. Секрети й токени зберігаються поза кодом і не потрапляють до журналу. У самому сповіщенні — лише посилання та номер: персональні дані й вміст документів до робочого чату не виносяться.

Що входить у роботу:
— карта подій із поясненням, навіщо потрібна кожна;
— приймання вебхуків із перевіркою підпису та відмовою всьому непідписаному;
— черга з повторними спробами і видимим залишком необробленого;
— захист від повторного опрацювання однієї події;
— маршрути в пошту та в месенджер команди — за подією і за адресатом;
— шаблони повідомлень зрозумілою мовою, без вивантаження сирих даних;
— журнал доставки з пошуком за подією та ручним повтором;
— спостереження за чергою і сигнал, коли вона перестала розвантажуватися;
— коротка інструкція для команди.