Если событие возврата приходит раньше обновления исходного платежа, не откладывайте 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 в отчёт не включайте.