Если перевозчик показывает «выдано», а сайт — «в пути», не исправляйте поле заказа вручную до разбора одного tracking ID. Соберите timeline: когда статус появился у перевозчика, был ли отправлен webhook, какой HTTP-ответ вернул сайт, попало ли событие в очередь и какая запись изменилась. Эта цепочка отделяет проблему внешней доставки от ошибки сопоставления или бизнес-правила внутри магазина.

Webhook — уведомление о событии, а не гарантия единственного и строго упорядоченного вызова. Поставщик может повторить доставку после таймаута, события могут прийти не по порядку, а обработчик — упасть после записи в базу, но до ответа 2xx. Поэтому статус заказа строится как воспроизводимая проекция событий с idempotency, а не как безусловное присваивание последнего пришедшего текста.

Timeline одного отправления показывает разрыв

ТочкаЧто найтиЕсли данных нет
кабинет/API перевозчикаtracking ID, code, event timeпроверить создание отправления
входящий endpointevent ID, received_at, status ответаURL, DNS, TLS и подписку
проверка подписирезультат без самого секретаraw body и актуальный ключ
очередьjob ID, retry, dead letterтранзакцию постановки и worker
сопоставлениеshipment/order IDформат tracking и tenant
запись состояниястарый/новый code и event timeтаблицу разрешённых переходов

Храните исходный event ID, внешний код, время события и время получения. Не логируйте адрес и телефон получателя. HTTP 200 в кабинете провайдера доказывает только принятие endpoint, если обработка выполняется позже. HTTP 500 без сохранённого события означает, что поставщик может повторить вызов; 200 до надёжной постановки в очередь рискует потерять событие навсегда.

Endpoint быстро подтверждает только надёжно принятую работу

verify_signature(raw_body, headers)
assert event.type in subscribed_types

begin transaction
  insert inbox(event_id, shipment_id, occurred_at, payload_hash)
    on conflict(event_id) do nothing
  enqueue process_delivery_event(event_id)
commit

return 204

Псевдокод показывает границу надёжности. Подпись проверяется по исходному телу, до разбора и изменения JSON. Уникальный event ID делает повтор безопасным. Если поставщик не даёт такого ID, составьте стабильный ключ из tracking ID, кода, времени события и версии источника, понимая ограничения. Секрет хранится вне кода, а его ротация поддерживает короткий период проверки старым и новым ключом.

Статусы перевозчика переводятся в собственную модель

  • внешние коды сохраняются отдельно от пользовательских названий;
  • несколько кодов перевозчика могут соответствовать одному состоянию магазина;
  • «ошибка адреса» или «ожидает в пункте» не обязаны завершать заказ;
  • время события сравнивается с уже применённым, чтобы старый retry не откатил доставку назад;
  • неизвестный новый код помещается в очередь разбора, а не превращается автоматически в «доставлено»;
  • переходы к конечным состояниям покрываются тестами для каждого подключённого перевозчика.

Сопоставление по одному только tracking number опасно, если номера могут повторяться у разных служб или аккаунтов. Ключ включает provider, account/tenant и tracking ID. При переоформлении отправления старый tracking закрывается, но остаётся связанным с заказом в истории; иначе позднее событие старой доставки изменит новое состояние.

Сверка API возвращает пропущенные события

Добавьте периодическое reconciliation-задание для активных отправлений: выбрать заказы без обновления дольше ожидаемого окна, запросить текущую историю у официального API и прогнать недостающие события через тот же обработчик. Это страховка от недоступности endpoint и ошибок подписки, а не основной способ синхронизации. Соблюдайте rate limits, делайте backoff и сохраняйте cursor.

Метрики должны отвечать на практические вопросы: возраст последнего события по активным отправлениям, доля ошибок подписи, размер и возраст очереди, неизвестные внешние коды, число несовпадений при сверке. Алерт на «нет webhook вообще» дополняется алертом на «webhook приходят, но ни один заказ не изменён» — второй ловит поломку mapping.

Восстановление начинают с replay, а не с массового UPDATE

  1. Исправить endpoint, mapping или worker и проверить на тестовом событии провайдера.
  2. Повторно обработать inbox/dead-letter для ограниченного диапазона event ID.
  3. Сверить десять отправлений с кабинетом/API и убедиться, что старые события не откатывают статус.
  4. Запустить reconciliation для активных заказов небольшими пакетами с лимитом запросов.
  5. Зафиксировать диапазон восстановления и число изменённых, пропущенных и спорных отправлений.

Для диагностики подготовьте обезличенный tracking ID, внешний code, event ID, timestamps, HTTP status и журнал очереди. Не присылайте webhook secret и персональные данные получателя. Перед replay сохраните snapshot затрагиваемых статусов и ограничьте выборку конкретным провайдером и периодом — так восстановление остаётся контролируемым и обратимым.

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