Обмен вебхуками и уведомления между сервисами

Два сервиса умеют обмениваться событиями десятком способов, и почти все они ломаются молча. Отправитель послал событие, приёмник в эту секунду перезагружался, повторной попытки не было — и о том, что клиенту не ушло подтверждение, вы узнаёте от самого клиента. Я собираю прослойку, которая делает такой обмен скучным и предсказуемым: приёмник событий, очередь за ним, маршрутизация оповещений и журнал доставки, по которому видно, дошло или нет.

Начинаю не с кода, а с разбора событий. Вместе проходим по тому, что реально происходит в ваших системах, и отбираем то, на что стоит реагировать: новый заказ, неудачная оплата, смена статуса, подписанный документ. Для каждого события записываю, кто должен о нём узнать, как быстро и по какому каналу. На этом шаге обычно исчезает половина будущего шума — раньше никто не спрашивал, заслуживает ли событие отдельного сообщения.

Дальше механика. Вебхук без проверки подписи не принимается — иначе событие может прислать кто угодно, а поддельное обходится дороже пропущенного. Принятые события уходят в очередь и повторяются с растущими паузами, пока принимающая сторона недоступна. Повторы в этом деле норма, поэтому у каждого события есть ключ, и вторая копия того же ключа не меняет ничего. Секреты и токены хранятся вне кода и не попадают в журнал. В самих уведомлениях — только ссылка и номер: персональные данные и содержимое документов в рабочий чат не выносятся.

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