Из-за временных ограничений на территории РФ наблюдаются проблемы с оплатой. Если платёж не проходит, оставьте запрос в службу поддержки.Служба поддержки работает 24/7 — мы всегда на связи по вопросам хостинга и серверов.Открыт прием заявок на аренду выделенных серверов и размещение оборудования в дата-центре.Напоминаем: рекомендуем включить резервное копирование для дополнительной защиты данных.Доступна новая линейка VPS/VDS с NVMe-дисками и увеличенной производительностью.Технические работы на части серверов завершены. Все сервисы работают в штатном режиме.
Статья11 мин чтенияПросмотры2

Webhook пришёл не по порядку: как не вернуть заказ к старому статусу

Разбираем, почему event_id без долговременной атомарной записи не защищает от повтора и как версия, обнаружение пропуска и сверка не дают позднему событию откатить заказ.

Комментарии 0

Женщина в светлой зоне комплектации отделяет запоздалую карточку события в лоток проверки рядом с посылкой
В этой статье

Если разные webhook одного заказа могут прийти не по порядку, одной дедупликации недостаточно. От точного повтора локального изменения защищает стабильный event_id источника: журнал события и новое локальное бизнес-состояние фиксируют в одной атомарной границе. Эта локальная транзакция сама по себе не делает атомарными внешние эффекты — фискальный чек, возврат или уведомление; для них нужны идемпотентность эффекта, outbox, отдельный журнал эффекта или компенсация по контракту интеграции. Получателя от обработки позднего устаревшего события защищает отдельная версия или другая метка порядка, смысл которой гарантирует источник. Если такой метки нет, безопаснее считать webhook сигналом и прочитать актуальное состояние объекта через API.

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

До сравнения порядка получатель должен проверить подпись или другой предусмотренный контрактом способ доверия к источнику, схему сообщения, тип версии и границы, в которых event_id остаётся уникальным. Иначе поддельное событие с большой версией способно остановить поток или вытеснить корректное состояние.

Дубль и устаревшее событие — разные случаи

У события, доставки и заказа разные идентификаторы. В материале о повторном webhook и идемпотентности уже разобран повтор одного event_id. Здесь другой отказ: два события имеют разные идентификаторы, но описывают разные версии одного заказа. Поэтому уникальное ограничение на event_id может сработать идеально, а статус всё равно откатится.

Вход

Что сравнить

Код модели

Бизнес-эффект

Новый event_id, следующая версия

version = stored + 1

applied

Применить один раз

Тот же event_id

Долговременный журнал событий

duplicate

Не повторять

Другой event_id, version ≤ stored

Версия объекта

stale

Не откатывать состояние

version > stored + 1 при непрерывной нумерации

Ожидаемая и полученная версии

gap

Остановить применение и сверить пропуск

Последняя строка допустима только тогда, когда контракт обещает последовательные версии без пропусков для одного объекта и всей области событий, важных вашему получателю. Если версия монотонна, но может перескакивать, или вы подписаны лишь на часть событий, значение 3 после 1 само по себе не доказывает потерю. Тогда более новую подтверждённую версию принимают по правилам источника либо сначала читают актуальный объект.

Нужно определить и область версии. Один счётчик может упорядочивать весь заказ, другой — только оплату или отгрузку. При независимых счётчиках равная версия с другим event_id может описывать отдельное допустимое действие, а не устаревшее событие. Правило version ≤ stored применимо только к той сущности и потоку, для которых контракт задаёт полный порядок.

Какую метку порядка можно использовать

В официальной документации Shopify о webhook прямо сказано: порядок не гарантирован даже внутри одной темы или между темами одного ресурса. Для организации событий сервис указывает на время возникновения и отдельно рекомендует периодически заново читать объекты источника и сопоставлять их с локальным состоянием. Это свойство Shopify, а не разрешение сортировать любой webhook по полю с похожим названием.

В официальной документации Google Cloud Pub/Sub сказано: порядок гарантируется только при оговорённых условиях. Сообщения должны иметь один непустой ordering key; у подписки настройка ordering должна быть явно включена; публикация должна соблюдать региональные условия. Глобального порядка между сообщениями с разными значениями ordering key нет. Очередь не создаёт гарантию задним числом: её нужно явно получить из контракта и конфигурации.

В официальном разборе Stripe также предупреждает, что события могут быть доставлены в любом порядке, и советует получать актуальный объект перед зависимым действием. Для интеграции это важная граница: снимок из старого события и текущее состояние у источника могут уже различаться.

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

Источник задаёт формат значения версии. JavaScript Number безопасен для учебных значений 1–3, но не обязан точно представлять произвольное 64-битное целое значение поля sequence. До внедрения проверьте диапазон и формат: иногда нужен BigInt, десятичная строка с согласованным сравнением или штатный comparator SDK.

Минимальная модель: применено, дубль, устарело и пропуск

Ниже — учебная модель, фактически выполненная 16 ноября 2026 года на Node.js v24.22.1 в Linux x64. Перед запуском создайте новый пустой каталог на тестовой машине, сохраните следующий блок как webhook-order-example.mjs и запускайте команду из этого каталога. Все входные события определены внутри файла; модель получает уже проверенные подпись, схему и тип полей, а event_id считается глобально уникальным в этом учебном потоке. Она не обращается к сети, не пишет другие файлы и не меняет внешние данные. После проверки удалите только созданный файл и ставший пустым тестовый каталог. Модель предполагает, что источник выдаёт каждому заказу последовательные версии без пропусков для всех отслеживаемых переходов.

import assert from 'node:assert/strict'; function createReceiver() { const orders = new Map(); const processedEvents = new Set(); return { apply(event) { if (processedEvents.has(event.eventId)) { return { result: 'duplicate', current: orders.get(event.orderId) ?? null }; } const current = orders.get(event.orderId) ?? { version: 0, status: 'unknown' }; if (event.version <= current.version) { processedEvents.add(event.eventId); return { result: 'stale', current }; } if (event.version > current.version + 1) { return { result: 'gap', expectedVersion: current.version + 1, receivedVersion: event.version, }; } const next = { version: event.version, status: event.status }; orders.set(event.orderId, next); processedEvents.add(event.eventId); return { result: 'applied', current: next }; }, get(orderId) { return orders.get(orderId) ?? null; }, }; } const receiver = createReceiver(); assert.equal(receiver.apply({ eventId: 'evt-1', orderId: 'order-42', version: 1, status: 'created', }).result, 'applied'); assert.deepEqual(receiver.apply({ eventId: 'evt-3', orderId: 'order-42', version: 3, status: 'paid', }), { result: 'gap', expectedVersion: 2, receivedVersion: 3 }); assert.equal(receiver.apply({ eventId: 'evt-2', orderId: 'order-42', version: 2, status: 'awaiting_payment', }).result, 'applied'); assert.equal(receiver.apply({ eventId: 'evt-3', orderId: 'order-42', version: 3, status: 'paid', }).result, 'applied'); assert.equal(receiver.apply({ eventId: 'evt-2', orderId: 'order-42', version: 2, status: 'awaiting_payment', }).result, 'duplicate'); assert.equal(receiver.apply({ eventId: 'evt-old', orderId: 'order-42', version: 2, status: 'cancelled', }).result, 'stale'); assert.deepEqual(receiver.get('order-42'), { version: 3, status: 'paid' }); console.log(JSON.stringify({ ok: true, final: receiver.get('order-42') }));

node webhook-order-example.mjs

{"ok":true,"final":{"version":3,"status":"paid"}}

Команда завершилась с кодом 0. Сначала версия 1 применяется. Версия 3 приходит раньше версии 2 и получает код gap — «пропуск версии», поэтому состояние не меняется. После версии 2 повторная доставка версии 3 применяется. Повтор evt-2 получает duplicate — «дубль», а другое событие с уже старой версией 2 получает stale: его версия устарела, но срок действия события здесь не оценивается. Итог остаётся paid/version 3.

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

Модель также начинает с локальной версии 0 и ожидает версию 1. Реальный объект может впервые прийти с версией 42. Для запуска получателя нужен отдельный начальный шаг: получить актуальный снимок и сохранить исходную версию либо принять первое событие только при документированном контракте полного снимка. Нельзя автоматически объявлять 1–41 потерянными.

Что делать при пропуске версии

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

Здесь важно разделить восстановление текущего состояния и воспроизведение каждого эффекта. Для проекции статуса может быть достаточно получить свежий снимок версии 5. Но если версии 3 и 4 запускали кассовый (фискальный) чек, возврат, отгрузку или уведомление, последний снимок не восстанавливает эти переходы. Тогда нужен backfill событий, отдельный журнал эффектов или согласованная компенсация — по контракту конкретной интеграции.

Материал о неизвестном статусе API решает соседнюю, но другую задачу: получатель не знает значение поля. Здесь значение известно, однако пришло слишком поздно. Оба случая нельзя закрывать значением по умолчанию.

Резервный сценарий без версии

Не придумывайте порядок из номера запроса, времени записи в вашем журнале или положения сообщения в текущем пакете. Webhook можно принять как сигнал об изменении, а затем запросить у источника актуальный заказ, оплату или отгрузку. Если API чтения временно недоступен, сохраните состояние pending_reconciliation — «ожидает сверки» — и выполните ограниченное число повторных попыток сверки по правилам конкретного сервиса.

Периодическая сверка нужна и при успешной доставке: webhook может быть пропущен из-за ошибки подписки, обработки или простоя. Сверка сравнивает объекты по устойчивому идентификатору и документированному признаку изменения, а не просто повторяет все побочные действия. Эта ветка основана на документации провайдеров; выполненный скрипт её не проверяет.

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

Критерии приёмки обработчика

  1. Зафиксируйте, что именно идентифицируют event_id, object_id и version/sequence; укажите область версии и уникальности, не подменяйте одно другим.

  2. До бизнес-логики проверьте подпись или иной контракт доверия, схему, обязательные поля и допустимый формат версии.

  3. Определите начальную синхронизацию для объекта, который впервые появляется не с версии 1.

  4. Проверьте новый переход, точный повтор того же event_id и другое событие со старой версией.

  5. Доставьте версию 3 после версии 1. Только при гарантированно непрерывной нумерации обработчик должен зафиксировать пропуск и не применять состояние молча.

  6. После устранения пропуска повторите версию 3 и убедитесь, что состояние движется только вперёд.

  7. Смоделируйте сбой между записью состояния и отметкой event_id в изолированном тестовом экземпляре той же СУБД и версии, без рабочих данных и секретов; обе записи должны иметь согласованную границу. После проверки удалите тестовые записи и стенд по заранее определённой процедуре.

  8. Запустите два обработчика одного объекта параллельно и проверьте атомарную защиту версии, а не только предварительный SELECT.

  9. Разделите тест восстановления свежего снимка и тест пропущенного необратимого эффекта.

  10. Отключите API чтения и проверьте ограниченный повтор сверки, наблюдаемую очередь и ручной путь без автоматического отката статуса.

  11. Сверьте метрики: возраст pending_reconciliation, число stale, duplicate и gap, долю успешных сверок и самый старый необработанный объект.

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

Обсуждение 0

Делись опытом и задавай вопросы. Комментарии без ссылок появляются после проверки редактором.

Пока никто не написал. Начни обсуждение.