API Gateway, который меняет JSON на лету, спасает от кривых вебхуков

API Gateway, который меняет JSON на лету, спасает от кривых вебхуков

Когда внешний сервис шлёт payload в формате «как получилось», не тащите это прямо в хендлер. Нормальный слой трансформации должен жить на границе: принять сырой JSON, провалидировать схему, привести поля к внутреннему контракту и только потом класть в очередь. Иначе каждая интеграция начинает знать чужие баги.

Практика простая:
— переименовать поля и выровнять типы;
— выкинуть мусорные ключи;
— добавить correlation_id, source, event_type;
— нормализовать даты, деньги и boolean'ы;
— отрезать лишнее до того, как оно попадёт в downstream.

Смотрим в тело запроса. Если payload не проходит минимальную валидацию, Gateway должен вернуть 4xx, а не «проглотить» мусор и устроить сюрприз через час в воркере. Если трансформация ломается внутри, это уже 5xx и ретрай-политика решает всё: повторяем только безопасные операции, а побочные эффекты прячем за идемпотентный ключ.

Типовой паттерн выглядит так: raw_json -> validate -> map -> enrich -> enqueue. Прокидываем стейт через метаданные, а исходник сохраняем отдельно для дебага. Тогда можно быстро понять, где именно умерла полезная нагрузка: на входе, в маппере или в consumer'е. Идемпотентность — это не роскошь, а база.

Если Gateway умеет только «принять и переслать», это не шлюз, а труба с лишним TLS. Нужен слой, который режет шум, стабилизирует контракт и не даёт внешнему API диктовать архитектуру внутри системы.