Вебхук

Что он несёт?

Событие, описывающее, что изменилось: платёж создан, замечен в сети, подтверждён, истёк или недоплачен. Точный словарь у провайдеров разный, форма — одна.

Он подписан. Проверить подпись до разбора чего бы то ни было — первое правило обработки, а каталог фиксирует, кто из провайдеров документирует API событий, потому что неподписанный запрос на вашем платёжном эндпоинте — не платёжное событие.

Почему это сложнее, чем кажется

Потому что сеть между двумя серверами ненадёжна, и ни одна сторона не различает режимы отказа. Провайдер, который отправил событие и не получил своевременного ответа, не знает, не получили ли вы его, получили и упали, или обработали успешно и не успели ответить.

Поэтому он повторяет. Значит, ваш обработчик обязан быть идемпотентным по идентификатору события и считать повтор пустой операцией. Гайд о вебхуках описывает полный набор требований.

Чем он не является

Гарантией. Вебхуки теряются, и платёжная система, доверяющая им как единственному источнику истины, рано или поздно пометит оплаченный заказ неоплаченным.

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

Сбой, на котором ловятся

Обработчик, который исполняет заказ прямо в запросе. В тестах он работает, под нагрузкой не укладывается в тайм-аут, а тайм-аут для провайдера выглядит как неудачная доставка, поэтому он повторяет, и нагрузка растёт.

Сначала подтвердите, потом работайте. Возвращайте 200, как только подпись проверена и событие записано, а исполняйте из очереди. Одно это изменение убирает класс сбоев, где медлительность наказывается дополнительным трафиком.