Если событие возврата приходит раньше обновления исходного платежа, не откладывайте HTTP-ответ в надежде, что данные «успеют». Проверьте подпись webhook, сохраните неизменный payload и идентификатор события в inbox, верните успешный ответ, а состояние платежа сверяйте отдельной фоновой задачей по API провайдера.

Порядок доставки нельзя использовать как бизнес-гарантию. Stripe прямо указывает, что события могут прийти не в порядке создания и иногда доставляются повторно. Локальная запись поэтому должна сходиться к фактическому состоянию платежа независимо от того, какой webhook оказался первым.

Webhook сообщает факт, но не завершает всю историю

НаблюдениеЧто оно означаетБезопасное действие
refund.created, payment ещё без refunded amountПроекции провайдера обновились не одновременноПоставить сверку payment и refund в очередь
Один event ID получен повторноПовторная доставкаВернуть 2xx без повторного побочного действия
Разные events описывают один refundНесколько стадий одного объектаСвести по provider refund ID и версии
Объект временно не найденРеплика или endpoint ещё не видит записьПовторить с backoff, не создавать новый возврат
Новая сумма меньше локальнойПришло устаревшее чтение или событиеНе откатывать монотонную сумму без отдельного reversal

Критичная граница проходит между «получить уведомление» и «выполнить возврат». Webhook уже созданного возврата не должен запускать второй refund API call. Он обновляет локальную проекцию, уведомления и бухгалтерские задачи только после проверки provider object.

Inbox принимает доставку один раз

BEGIN
  verify_signature(raw_body, signature_header)
  INSERT webhook_inbox(provider, event_id, type, payload)
    ON CONFLICT (provider, event_id) DO NOTHING
  COMMIT
  enqueue reconcile_refund(provider_refund_id)
RETURN 200

Уникальный индекс на паре provider/event_id закрывает обычный повтор. Для двух разных событий об одном объекте добавьте бизнес-ключ provider_refund_id и делайте изменения идемпотентными: запись статуса — upsert, письмо — через outbox с уникальным notification key, движение денег — только по подтверждённому transaction ID.

Сверка читает связанные объекты, а не один флаг

Worker получает refund, затем исходный payment и при необходимости balance transaction. Сравнивайте валюту, сумму, связь с платежом и статус возврата. Если провайдер ещё возвращает противоречивый снимок, оставьте задачу в состоянии awaiting_provider и повторите её с ограниченным backoff.

  • Не сортируйте независимые события только по timestamp: несколько событий могут иметь одинаковую секунду.
  • Не используйте номер попытки доставки как версию бизнес-объекта.
  • Не отправляйте клиенту «деньги возвращены», пока возврат находится в pending.
  • Храните последний provider status и время фактической сверки отдельно от времени webhook.
  • После исчерпания retry переводите задачу в ручную очередь, не инициируя новый refund.

Проекция обновляется монотонно

Опишите допустимые переходы refund: requested → pending → succeeded либо failed/canceled в терминах конкретного провайдера. Позднее событие о pending не должно вернуть succeeded назад. Исключения вроде reversal оформляются отдельным типом перехода с собственным идентификатором и аудитом.

Если provider API не даёт version, вычисляйте локальную версию из устойчивых признаков: статус, confirmed amount, provider updated_at и набор transaction IDs. Это не заменяет документацию провайдера, но делает решение о применении изменения прозрачным.

Проверка намеренно меняет порядок

В тестовом окружении передайте refund event, затем старый payment snapshot, повтор того же event и только потом обновлённый payment. Успех — один refund в базе, одно уведомление после подтверждения, правильная сумма и пустая retry-очередь после сходимости.

Для разбора сбоя подготовьте provider event IDs, типы событий, timestamps получения, обезличенные статусы payment/refund и журнал попыток reconcile. Payload с персональными данными, ключи API и подпись webhook в отчёт не включайте.

Проверенные источники