Если перевозчик показывает «выдано», а сайт — «в пути», не исправляйте поле заказа вручную до разбора одного tracking ID. Соберите timeline: когда статус появился у перевозчика, был ли отправлен webhook, какой HTTP-ответ вернул сайт, попало ли событие в очередь и какая запись изменилась. Эта цепочка отделяет проблему внешней доставки от ошибки сопоставления или бизнес-правила внутри магазина.
Webhook — уведомление о событии, а не гарантия единственного и строго упорядоченного вызова. Поставщик может повторить доставку после таймаута, события могут прийти не по порядку, а обработчик — упасть после записи в базу, но до ответа 2xx. Поэтому статус заказа строится как воспроизводимая проекция событий с idempotency, а не как безусловное присваивание последнего пришедшего текста.
Timeline одного отправления показывает разрыв
| Точка | Что найти | Если данных нет |
|---|---|---|
| кабинет/API перевозчика | tracking ID, code, event time | проверить создание отправления |
| входящий endpoint | event 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
- Исправить endpoint, mapping или worker и проверить на тестовом событии провайдера.
- Повторно обработать inbox/dead-letter для ограниченного диапазона event ID.
- Сверить десять отправлений с кабинетом/API и убедиться, что старые события не откатывают статус.
- Запустить reconciliation для активных заказов небольшими пакетами с лимитом запросов.
- Зафиксировать диапазон восстановления и число изменённых, пропущенных и спорных отправлений.
Для диагностики подготовьте обезличенный tracking ID, внешний code, event ID, timestamps, HTTP status и журнал очереди. Не присылайте webhook secret и персональные данные получателя. Перед replay сохраните snapshot затрагиваемых статусов и ограничьте выборку конкретным провайдером и периодом — так восстановление остаётся контролируемым и обратимым.