Skip to main content
ГоловнаБлогПосібникиЯк узгодити пропущені оновлення Webhook із періодичним опитуванням API: практичний посібник із гібридної синхронізації

Як узгодити пропущені оновлення Webhook із періодичним опитуванням API: практичний посібник із гібридної синхронізації

17TRACK

Використовуйте вебхуки для оперативних оновлень і періодичне опитування API, щоб перевіряти, чи все ще відповідає ваш локальний запис про відправлення запису постачальника. Надійний підхід полягає в тому, щоб надійно зберігати доставки вебхуків, узгоджувати дані з API за стабільними ідентифікаторами відправлень і обробляти обидва шляхи через одну й ту саму ідемпотентну логіку оновлення. Опитування може виправити пропущені зміни стану, але не може відновити проміжні події, якщо API фактично не надає історію подій.

Як узгоджувати пропущені оновлення вебхуків із періодичним опитуванням API

Цей посібник призначений для інженерів і операційних команд, відповідальних за синхронізацію системи керування замовленнями, сторінки відстеження або представлення для служби підтримки клієнтів із даними про відправлення. Його головне правило просте: розглядайте вебхук як сигнал для перевірки та обробки зміни, а не як доказ того, що надійшла кожна попередня зміна.

Визначте, що означає «синхронізовано», перш ніж обирати інтервал

Інтеграції відправлень може знадобитися зберігати дві різні речі: поточний стан, наприклад «у дорозі» або «доставлено», і історію подій, яка пояснює, як відправлення до нього дійшло. Пошук відправлення у постачальника може повертати останній стан, список подій відстеження або обидва варіанти. Ці формати API забезпечують різні гарантії відновлення.

Якщо пошук повертає лише знімок поточного стану, опитування для узгодження може виправити локальний статус після пропущеного вебхука. Воно не може підтвердити, які проміжні статуси виникали. Якщо API повертає історичні події зі стабільними ідентифікаторами або часовими мітками, опитування також може відновити відсутні записи часової шкали. Перш ніж обіцяти користувачам нижчого рівня будь-який із цих результатів, перевірте фактичну схему відповіді постачальника.

Запишіть поля, які ваша програма має узгоджувати: ідентифікатор відправлення, перевізника або ідентифікатор відстеження, нормалізований статус, статус постачальника, час події, час останнього оновлення постачальника, деталі доставки та будь-які поля, що використовуються для запуску повідомлень клієнтам. Відокремте поля, авторитетні для постачальника, від полів, якими володіє локальна система, наприклад внутрішньої примітки до звернення. Завдання узгодження не повинно перезаписувати дані, що існують лише локально, лише тому, що вони відсутні у відповіді API.

Створіть єдиний шлях обробки результатів вебхуків і опитування

Обробники вебхуків і працівники опитування не повинні реалізовувати конкуруючі правила для змін статусу. Обидва компоненти мають створювати нормалізоване спостереження та передавати його одній функції узгодження. Ця функція перевіряє ідентичність, порівнює спостереження зі збереженим відправленням, виконує безпечне оновлення та записує причину зміни.

  1. Отримання й автентифікація. Перевіряйте вебхук за задокументованим механізмом постачальника. Відхиляйте запити, які не проходять перевірку, але зберігайте достатньо нечутливої діагностичної інформації для розслідування проблем із доставкою.
  2. Збереження до підтвердження. Поміщайте коректну доставку в надійне сховище або чергу до повернення успішної відповіді. Успішна відповідь HTTP, надіслана до збереження, створює прогалину, яку повторна спроба постачальника може не усунути.
  3. Нормалізація. Перетворюйте дані постачальника або відповідь API на спільну внутрішню структуру, зберігаючи початкові значення постачальника для розслідування.
  4. Узгодження. Використовуйте стабільний ключ відправлення та правило ідемпотентності, щоб запобігати дублюванню записів часової шкали, повторним сповіщенням і непотрібним записам.
  5. Аудит результату. Записуйте, чи змінило спостереження відправлення, чи було вже відомим, чи було старішим за збережений стан або потребує ручної перевірки.

Ідентифікатор події постачальника корисний для дедуплікації, якщо він існує та є стабільним. Якщо його немає, може знадобитися складений ключ, але його компоненти мають відповідати моделі даних постачальника. Два справжні сканування можуть мати однакові статус і часову мітку, тому ключ, побудований лише з цих полів, може відкинути реальну подію. Зберігайте необроблені дані або посилання на них протягом визначеного періоду зберігання, щоб можна було досліджувати неоднозначні збіги.

Проєктуйте цикл опитування з огляду на ризик, а не на один глобальний таймер

Опитування кожного відомого відправлення з однаковою частотою марнує запити та може створювати навантаження на ліміти API. Підтримуйте набір відправлень, придатних для узгодження, і вибирайте їх відповідно до операційного ризику. Нове зареєстроване відправлення, яке ще не отримало першого оновлення, відправлення з нещодавньою помилкою обробки вебхука та відправлення, статус якого не змінювався протягом очікуваного процесу, можуть потребувати різних розкладів. Для завершеного відправлення може бути достатньо обмеженої фінальної перевірки — залежно від того, наскільки важливі для вашої програми пізні виправлення.

Обирайте інтервал, виходячи з максимального часу, протягом якого ваша компанія може терпіти неправильний локальний статус. Враховуйте затримку черги, час запиту, повторні спроби та потужність працівників; сам інтервал опитування не є часом відновлення. Додавайте випадкове зміщення, щоб багато відправлень не ставали готовими до обробки в один момент. Якщо постачальник документує обмеження запитів або пропонує пакетний пошук, враховуйте ці обмеження, а не припускайте, що рішення, яке працює в невеликому тесті, масштабуватиметься без змін.

Зберігайте облік планувальника окремо від стану постачальника. Поля на кшталт last_poll_attempt_at, last_successful_poll_at, next_poll_at і last_webhook_received_at відповідають на різні запитання. Зокрема, невдала спроба опитування через тайм-аут не повинна оновлювати маркер успішного опитування.

Коли API підтримує умовні запити, задокументований курсор змін або фільтр updated-since, оцініть, чи зменшує це непотрібну передачу даних, не приховуючи записи. HTTP визначає поведінку умовних запитів, зокрема відповідь 304 Not Modified, але інтеграція має використовувати її лише тоді, коли відповідна кінцева точка це підтримує, а її семантика зрозуміла. Курсор не є взаємозамінним із часовою міткою: підтвердьте, що саме він упорядковує, чи належить до облікового запису або відправлення та як поводиться під час розбиття результатів на сторінки.

Узгоджуйте дані, не відкочуючи новіше оновлення

Найпоширеніша гонка проста: починається опитування, потім надходить новіший вебхук, а опитування повертає старіший знімок. Якщо записати результат опитування останнім без порівняння, локальне відправлення повернеться назад. Запобігайте цьому, перевіряючи час події або версію постачальника, якщо вони надійні, і роблячи порівняння та запис атомарними для кожного відправлення.

Не припускайте, що час надходження відображає порядок подій. Вебхук, доставлений із затримкою, може описувати старіше сканування, тоді як пізніша відповідь API може містити виправлення раніше повідомленої події. Визначте окремі правила для додавання до часової шкали та вибору поточного стану. Наприклад, старе сканування може належати до історії, не замінюючи поточний статус. Виправлення постачальника може вимагати зміни збереженої події, а не додавання ще однієї. Правильне правило залежить від ідентифікаторів, часових міток і сигналів редакцій, які надає постачальник.

Якщо постачальник не пропонує надійного поля версії або порядку, дійте консервативно. Порівнюйте весь повернений запис із локальним, позначайте суперечності та не розглядайте мітку статусу як універсальну схему порядку. «Виняток», «кур’єр прямує для доставки» та «доставлено» не завжди утворюють просту лінійну послідовність, особливо коли перевізник пізніше виправляє сканування. Зберігайте необроблені значення постачальника разом із нормалізованим статусом, щоб людина могла перевірити сумнівні випадки.

Побічні ефекти потребують такої самої дисципліни, як і зберігання. Опитування, яке виявляє статус «доставлено», не повинно надсилати друге повідомлення про доставку, якщо вебхук уже спричинив перше. Зробіть сповіщення та наступні завдання ідемпотентними щодо надійного бізнес-ключа, наприклад ідентифікатора відправлення разом із визначеним переходом або ідентифікатором події постачальника. Оновлення бази даних і зовнішнє сповіщення зазвичай не можна розглядати як одну автоматичну операцію; транзакційний outbox або еквівалентний надійний запис роботи може допомогти гарантувати, що за зафіксованою зміною відбудеться одна контрольована спроба обробити її побічний ефект.

Виконуйте обмежене пакетне відновлення після збою

Регулярне опитування не замінює явної процедури відновлення. Коли кінцева точка вебхука, черга або працівник були недоступні, спочатку визначте порушений період і набір відправлень. Додайте відправлення, які були активними під час збою, а не лише ті, що позначені як активні зараз: одне з них могло досягти кінцевого статусу, поки оновлення пропускалися.

Починайте пакетне відновлення достатньо рано до передбачуваного збою, щоб врахувати затриману доставку та невизначеність часу виявлення. Це перекриття навмисно повторно обробляє частину вже відомих даних; ідемпотентність робить це безпечнішим, ніж залишення прогалини. Обробляйте результати керованими пакетами, надійно відстежуйте прогрес і зберігайте невдалі елементи для повторної спроби. Не переміщуйте контрольну точку пакетного відновлення лише тому, що сторінку було запитано. Переміщуйте її лише після обробки записів сторінки або явної фіксації їх як невирішених.

Якщо API пропонує розбиття на сторінки, перевірте порядок і поведінку продовження, перш ніж використовувати номер сторінки або курсор як контрольну точку відновлення. Якщо API пропонує лише знімки для окремих відправлень, сформуйте список постраждалих відправлень із власних записів і узгодьте кожне з них. Задокументуйте обмеження цього методу: поточні статуси можуть бути правильними, хоча деякі проміжні сканування залишаться недоступними.

Тестуйте очікувані випадки відмов, які потрібно виправляти

Корисний план тестування виходить за межі надсилання одного вебхука та перевірки однієї відповіді API. Перевірте повторні доставки вебхуків, надходження старішого вебхука після новішого, надходження відповіді опитування після вебхука, часткові збої API, перезапуски працівників і збій між збереженням стану відправлення та плануванням сповіщення. Перевіряйте і видимий запис відправлення, і журнал побічних ефектів.

Також протестуйте пакетне відновлення після збою з кількістю записів, що перевищує розмір одного пакета. Переконайтеся, що перезапуск завдання безпечно повторює невеликий обсяг роботи, а не пропускає записи. Якщо API повертає історичні події, перевірте, чи з’являється те саме сканування у форматах вебхука та опитування і чи розпізнає його ваше правило дедуплікації. Якщо API повертає лише знімки, переконайтеся, що інтерфейс не подає передбачену проміжну подію як фактично спостережене сканування перевізника.

Операційний моніторинг має розрізняти три сигнали: стан доставки вебхуків, стан опитування та актуальність даних. Корисні показники включають вік останнього успішного узгодження для придатних відправлень, кількість невирішених невідповідностей, вік черги, частоту помилок API та розмір черги відновлення. Сама по собі здорова кінцева точка вебхука не доводить, що локальний стан відправлення актуальний.

Застосуйте цей посібник до API відстеження

Для інтеграції відстеження відправлень почніть із задокументованих ідентифікаторів постачальника, даних вебхуків, відповідей пошуку відправлень, вимог автентифікації та обмежень запитів. Якщо ви використовуєте Tracking API 17TRACK, ознайомтеся з його офіційною документацією API перед реалізацією опитувача. Підтвердьте доступні для вашої інтеграції механізми пошуку й оновлення, а не припускайте, що кожен обліковий запис або кінцева точка підтримує історичне відтворення, пакетне відновлення на основі курсора чи умовні запити.

Рішення полягає не у виборі між «вебхуками або опитуванням». Використовуйте вебхуки для зменшення звичайної затримки оновлень, опитування — для виявлення та виправлення невідповідностей, які може показати доступний API, а явну процедуру пакетного відновлення — для інцидентів. Зазначте межу відновлення у своєму регламенті: чи може система відновити поточний статус, історію подій або обидва варіанти. Саме ця межа визначає, чи стане пропущене оновлення короткочасно застарілим поданням або постійною прогалиною в записі.

Поширені запитання

Чи може опитування гарантувати, що жодна подія відстеження не буде пропущена?

Ні. Пошук поточного стану може показати, що останній статус змінився, але не може відновити проміжну подію, яку API не повертає. Для відновлення історичних подій потрібні доступна історія подій і надійний спосіб ідентифікувати або порівнювати її записи.

Чи має вебхук запускати негайне опитування API?

Лише тоді, коли пошук через API додає інформацію, потрібну вашій програмі, або коли вебхук навмисно є сповіщенням про зміну, а не повним записом. Опитування після кожного вебхука може створити надлишкові запити. Якщо вебхук містить достатньо надійних даних, обробляйте його безпосередньо, а перевірки API залишайте для запланованого узгодження або цільового розслідування.

Що робити, якщо опитування API та вебхук не збігаються?

Порівняйте часові мітки постачальника, версії, ідентифікатори та значення даних перед вибором поточного стану. Збережіть обидва спостереження. Якщо постачальник не надає надійного сигналу порядку, а розбіжність впливає на важливу дію, позначте відправлення для перевірки, а не мовчки обирайте відповідь, яка надійшла останньою.

Коли слід припиняти опитування для доставленого відправлення?

Використовуйте задокументовану політику, засновану на тому, чи важливі для вашої програми пізні виправлення перевізника, деталі підтвердження доставки або наступні робочі процеси. Сам по собі статус, що виглядає кінцевим, не доводить, що постачальник більше ніколи не оновить запис.

Як опитувач має обробляти обмеження частоти запитів?

Зменшуйте навантаження запитами, повторюйте спроби з експоненційною затримкою та дотримуйтеся заголовка Retry-After, якщо сервер його надає. Визначайте пріоритет для відправлень із найбільшою потребою у відновленні замість одночасного повторного опитування кожного відправлення. Семантика HTTP визначає відповідь 429 Too Many Requests і поле Retry-After; обмеження конкретної кінцевої точки все одно потрібно перевіряти в документації постачальника.

Джерела

  • RFC 9110: Семантика HTTP — умовні запити, 304 Not Modified, 429 Too Many Requests і Retry-After.
  • 17TRACK Tracking API — офіційний опис продукту для інтеграцій відстеження відправлень.
  • Документація API 17TRACK — офіційний довідник для перевірки поведінки кінцевих точок і вимог інтеграції.