Webhook арқылы жөнелтілімді қадағалау: Қадағалау webhook-тары polling-пен салыстырғанда қалай жұмыс істейді (payload-тар, қайталап жіберу және баптау)

Жөнелтуді қадағалау вебхуктары қадағалау қызметінде хабарлауға тиіс жаңарту болған кезде қолданбаңызға HTTP сұрауын жібереді. Polling кері бағытта жұмыс істейді: қолданбаңыз қадағалаудың ең соңғы ақпаратын қайта-қайта сұратады. Жөнелту деректерін тапсырыстарды басқару жүйесіне, дүкенге немесе тұтынушыларға хабарлау қызметіне қосатын әзірлеушілер үшін вебхуктар, әдетте, қолдау көрсетілген жағдайда негізгі жаңарту механизмі ретінде тиімдірек; ал мақсатты polling өткізіп алған жаңартуларды қалпына келтіруге және жазбаларды салыстырып сәйкестендіруге көмектеседі.

Екі әдістің де тасымалдаушының сәлемдемені ертерек сканерлеуіне ықпалы жоқ. Екеуі де қадағалау көзі жаңа ақпаратты қашан қабылдап, қолжетімді ететініне тәуелді. Практикалық айырмашылық қолданбаңыздың бұл ақпаратты қалай алатынында, қанша сұрау трафигін жасайтынында және жеткізу сәтсіз болғанда не болатынында.

Қадағалау вебхуктары мен polling: операциялық айырмашылық

Бұлар бәсекелес қадағалау дерекқорлары емес, интеграция үлгілері. Тасымалдаушы немесе қадағалау платформасы осы үлгілердің біреуін немесе екеуін де ұсына алады және олардың қолжетімділік шарттары әртүрлі болуы мүмкін. Барлық вебхук қызметтерінің кепілдіктері бірдей деп болжамай, пайдалануды жоспарлаған нақты API-дің әрекетін салыстырыңыз.

Жаңартулардың уақтылығы маңызды болса және командаңыз сенімді қабылдағышты басқара алса, алдымен вебхуктарды таңдаңыз. Кіріс endpoint-тері қолайсыз болса, жөнелту көлемі аз болса немесе дереккөз қолайлы вебхуктар ұсынбаса, алдымен polling таңдаңыз. Өткізіп алған жаңартулар тұтынушылармен байланысқа немесе операцияларға кедергі келтіруі мүмкін және API салыстырып сәйкестендіруді қолдаса, гибридті дизайнды қолданыңыз.

Вебхуктар арзанырақ болады деп болжамаңыз. Жазылым ақысы, қадағалауды тіркеу, API қоңыраулары, оқиғаларды жеткізу және инфрақұрылым әртүрлі есептелуі мүмкін. Сұраулар санының аз болуы төлемнің төмен екенін дәлелдейді деп қарамай, нақты коммерциялық шарттар мен күтілетін жұмыс көлемін салыстырыңыз.

Тасымалдаушы сканерлеуі мен қолданбаңыздың арасында не болады?

1. Жөнелтуді анықтаңыз. Қадағалау нөмірін, қажет болса тасымалдаушы туралы ақпаратты және ішкі жөнелту сілтемесін байланыстырыңыз. Кейбір қызметтер бақылау басталғанға дейін тіркелуді талап етеді.
2. Оқиғаларды жеткізуді реттеңіз. HTTPS callback URL мекенжайын беріп, қолдау көрсетілетін оқиға жазылымдарын таңдаңыз.
3. Дереккөз қадағалау ақпаратын қабылдайды. Тасымалдаушының сканерлеуі немесе мәртебе өзгерісі қадағалау қызметіне қолжетімді болады.
4. Қызмет вебхук жібереді. Сұрауда қадағалаудың толық суреті, бір бақылау нүктесі немесе API арқылы іздеуді қажет ететін сілтеме ғана болуы мүмкін.
5. Қабылдағышыңыз тексеріп, сақтайды. Сұрауды аутентификациялаңыз, құрылымын тексеріңіз және оқиғаны тұрақты түрде жазып алыңыз немесе кезекке қойыңыз.
6. Жұмысшы бизнес жүйелерін жаңартады. Мәртебелерді қалыпқа келтіріңіз, жөнелту жазбаларын жаңартыңыз және әлі де орынды әрекеттерді ғана іске қосыңыз.

Вебхуктың жеткізілуі физикалық жеткізумен бірдей емес. Ол жөнелту туралы ақпарат жөніндегі хабарлама. Сол сияқты сәтті вебхук жауабы электрондық хат жіберілгенін немесе тапсырыс жазбасы жаңартылғанын дәлелдемейді; бұлар өз мониторингі қажет кейінгі өңдеу нәтижелері.

Қадағалау вебхугының payload-ын оқу

Төмендегі JSON — иллюстрациялық интеграция дизайны, 17TRACK payload-ы немесе әмбебап схема емес. Нақты өріс атаулары, мәртебе кодтары, уақыт белгісі пішімдері және оқиға идентификаторлары таңдалған провайдердің құжаттамасынан алынуы керек.

{
  "event_id": "evt_example_001",
  "event_type": "shipment.updated",
  "created_at": "2025-04-08T10:16:00Z",
  "shipment": {
    "reference": "shipment_example_123",
    "tracking_number": "EXAMPLE123456",
    "carrier_code": "example_carrier",
    "status": "in_transit",
    "checkpoint": {
      "occurred_at": "2025-04-08T10:10:00Z",
      "description": "Departed processing facility"
    }
  }
}

Деректер моделінде үш уақытты бөлек сақтаңыз: жөнелту оқиғасы болған уақыт, провайдер хабарламаны жасаған уақыт және қолданбаңыз оны қабылдаған уақыт. Кешіккен бақылау нүктесі жаңарақ нүктеден кейін келуі мүмкін. Ығысуы көрсетілмеген уақыт белгісі де нақты түсіндірмені қажет етеді; әр тасымалдаушының жергілікті уақыт белгісін UTC деп үнсіз қабылдамаңыз.

Ішкі жөнелту сілтемесін провайдердің идентификаторларымен бірге сақтаңыз. Әсіресе әртүрлі тасымалдаушы мәнмәтіндерінде тек қадағалау нөмірі тұрақты жаһандық идентификатор ретінде жеткіліксіз болуы мүмкін. Бөлінген тапсырыстар үшін бір сәлемдеменің жеткізілді мәртебесі бүкіл тапсырысты аяқталған деп белгілемеуі үшін жөнелту деңгейіндегі жазбаларды жүргізіңіз.

Бастапқы мәртебе мен сипаттаманы қалыпқа келтірілген бизнес мәртебесімен қатар сақтаңыз. Қолданбаңыз бірнеше тасымалдаушы хабарламасын «жолда» мәртебесіне түрлендіруі мүмкін, бірақ қолдау қызметкерлеріне кідірісті түсіну үшін бастапқы бақылау нүктесі әлі де қажет болуы ықтимал. Болжалды жеткізу күндерін болжам ретінде қарастырыңыз және жетіспейтін өрісті бар мәнді тазалау туралы нақты нұсқаудан ажыратыңыз.

Қайталап жіберу, растау және қайталанатын оқиғалар

Вебхук жеткізілімі тайм-ауттар, желі үзілістері, аутентификация қателері немесе қабылдағыштың қолжетімсіздігі салдарынан сәтсіз болуы мүмкін. Провайдер қайталап жіберуі мүмкін, бірақ қайталап жіберудің әмбебап кестесі, сақтау терезесі немесе әрекеттердің ең көп саны жоқ. Қай жауаптар тағы бір әрекетті іске қосатынын, қайта бағыттаулардың қалай өңделетінін және қолмен қайта жеткізу қолжетімді ме екенін анықтаңыз.

Тұрақты қабылдаудан кейін растаңыз

Сұрау жолын қысқа ұстаңыз: сұрауды тексеріңіз, қабылданған жұмысты сақтаңыз және провайдер талап ететін сәтті жауапты қайтарыңыз. Электрондық хаттарды жіберу мен баяу бизнес операцияларын асинхронды орындаңыз. HTTP спецификациясы 202 Accepted кодын өңдеуге қабылдау, ал өңдеудің аяқталуы емес деп анықтайды, бірақ провайдеріңіз басқа сәтті жауапты талап етуі мүмкін. Оның вебхук келісімшартын орындаңыз.

Ештеңе сақтамай тұрып сәтті жауап қайтару процесс істен шықса, жаңартуды жоғалту қаупін тудырады. Барлық кейінгі әрекеттерді күту тайм-аутқа және тағы бір жеткізу әрекетіне әкелуі мүмкін. Тұрақты inbox немесе кезек қабылдау мен өңдеу арасында шекара жасайды.

Өңдеуді идемпотентті етіңіз

Идемпотенттілік бір оқиғаны қайта өңдеу оның бизнес әсерлерін қайталамайтынын білдіреді. Серверіңіз оқиғаны қабылдағаннан кейін растау жоғалса, жіберуші қайта әрекет етуі мүмкін. Сондықтан қайталанатын жеткізуді әдеттегі тест жағдайы ретінде қарастырыңыз.

• Қолжетімді болса, құжатталған оқиға идентификаторын дұрыс провайдер немесе аккаунт аясындағы қайталануды жою кілті ретінде пайдаланыңыз.
• Идентификатор болмаса, тұрақты оқиға өрістерінен құрама кілт жасап, оның қақтығысу тәуекелдерін тексеріңіз.
• Дерекқорда бірегейлікті атомарлы түрде қамтамасыз етіңіз; бөлек «тексеру, содан кейін енгізу» реттілігі қатар жеткізу кезінде жарыс жағдайына ұшырауы мүмкін.
• Кейінгі әрекеттерді де қорғаңыз. Қайталанатын оқиға басқа жеткізу хабарламасын жібермеуі немесе қаржылық әрекетті қайталамауы тиіс.
• Сақтау мерзімін провайдердің қайта ойнату әрекетіне және қалпына келу талаптарына сай белгілеңіз, қайталануды жою жазбаларын бірден өшірмеңіз.

Оқиғалар хронологиялық ретпен келеді деп болжамаңыз

Сұрау соңғы болып келгені үшін ағымдағы жөнелту күйін қайта жазбаңыз. Оқиғаның мәнін, уақыт белгілерін және құжатталған реттік ақпаратты салыстырыңыз. Кеш келген бақылау нүктелерін тарихта сақтаңыз, бірақ көрсетілетін мәртебені автоматты түрде кері өзгертпеңіз. Сонымен бірге құжатталған түзетулерге мүмкіндік беріңіз: жеткізілді деп белгіленген жөнелтулер ешқашан өзгермейді деген қатаң ереже заңды ерекшеліктерді немесе түзетілген ақпаратты жасыруы мүмкін.

Практикалық орнату бақылау тізімі

1. Провайдер келісімшартын растаңыз

Іске асырудан бұрын тіркеу талаптарын, қолдау көрсетілетін оқиғаларды, payload құрылымын, аутентификацияны, жауап талаптарын, тайм-ауттарды, қайталап жіберу әрекетін және API шектеулерін растаңыз. Хабарлама snapshot па, әлде инкременттік өзгеріс пе, жеткізілімде бірнеше жазба болуы мүмкін бе және жазылу бастапқы күйді жібере ме — тексеріңіз.

17TRACK интеграциясы үшін ресми Tracking API page және API documentation беттерінен бастаңыз. Сұрау өрістері мен callback талаптарын анықтау үшін провайдерге тән құжаттаманы пайдаланыңыз; жоғарыдағы жалпы payload оның орнын баспайды. Орнатуды жоспарлаған интеграцияның қолжетімділік шарттары мен операциялық шектеулерін растаңыз.

2. Қабылдайтын endpoint-ті қорғаңыз

HTTPS және провайдер құжаттаған аутентификация механизмін пайдаланыңыз. Егер HMAC қолтаңбасын қолданса, ол көрсеткен қол қойылған кірісті дәл тексеріңіз. Шикі сұрау байттарына қол қойылса, тексеруден бұрын JSON-ды талдау және қайта сериализациялау байттарды өзгертіп, қолтаңбаны жарамсыз етуі мүмкін. Құпия мәннен алынған қолтаңбаларды салыстыру үшін тұрақты уақытты салыстыруды пайдаланыңыз.

Қолтаңбаланған уақыт белгілері немесе жеткізу идентификаторлары қолжетімді болса, құжатталған қайта ойнатудан қорғау құралдарын қолданыңыз. Жарамды қолтаңба хабарламаның түпнұсқалығын растайды, бірақ оның жаңа екенін өздігінен дәлелдемейді. Құпияларды URL мекенжайлары мен қолданба журналдарынан тыс сақтаңыз, құпияларды ауыстыруды қолдаңыз және сұрау өлшемдерін шектеңіз. IP allowlisting қолжетімді мекенжай ауқымдары тұрақты болған жағдайда қосымша бақылау құралы бола алады, бірақ хабарлама аутентификациясының орнын баспайды.

3. Қабылдауды бизнес өңдеуінен бөлек ұстаңыз

Қабылданған оқиғаны бақылауға және қауіпсіз қайта ойнатуға жеткілікті ақпарат сақтаңыз. Кезек жұмысшылары жаңартуды қалыпқа келтіріп, күй ауысу ережелерін қолданып, әрекет нәтижелерін жазуы керек. Қайта-қайта сәтсіз болатын жұмысты шексіз қайталаудың орнына тексеруге болатын dead-letter үдерісіне жіберіңіз. Қолжетімділік пен сақтау мерзімін шектеңіз, себебі қадағалау payload-тарында тұтынушыға қатысты ақпарат болуы мүмкін.

4. Іске қоспас бұрын сәтсіздік жолдарын тексеріңіз

• Бір оқиғаны, соның ішінде қатар жеткізулерді, екі рет жіберіңіз.
• Жаңарақ бақылау нүктесінен кейін ескісін жеткізіңіз.
• Кезек істен шығуын және қабылдаудан кейін жұмысшының істен шығуын модельдеңіз.
• Жарамсыз аутентификацияны, қате JSON-ды және шамадан тыс үлкен сұрауларды тексеріңіз.
• Белгісіз жөнелтулерді, жоқ қосымша өрістерді және қосылған өрістерді тексеріңіз.
• Бір жеткізілген сәлемдеме бөлінген тапсырысты аяқтамайтынын тексеріңіз.
• Қалпына келгеннен кейін оқиғаны қайта ойнатып, хабарламалардың қайталанбайтынын растаңыз.

Қауіпсіз болған жағдайда қосымша өрістерге төзімді болыңыз, бірақ белгісіз мәртебе мәндерін үнсіз қайта түсіндірмеңіз. Шикі мәнді сақтап, танылмаған жағдайларды анықталған резервтік немесе тексеру үдерісіне бағыттаңыз.

Polling әлі де пайдалы болатын жағдайлар

Polling бастапқы синхрондау, істен шыққаннан кейін қалпына келу және күтілген жаңартулары келмеген жөнелтулерді тексеру үшін пайдалы. Алайда үнсіздік вебхуктың істен шыққанына дәлел емес: сәлемдемеде шынымен жаңа сканерлеулер болмауы мүмкін. Әрбір тыныш жөнелтуге ескерту қажет деп болжамай, API-дің ағымдағы күйімен немесе тарихымен салыстырыңыз.

Масштабты жоспарлау үшін жеңілдетілген polling моделі — requests per hour ≈ active shipments × polls per shipment per hour, мұнда бір сұрауға бір жөнелту алынады. Batch endpoint-тері бұл есепті өзгертеді. Мысалы, 1 000 жөнелтуді сағатына төрт рет тексеру қайталап жіберулерді есептемегенде сағатына 4 000 сұрау жасайды; бұл арифметикалық мысал, провайдер квотасы немесе баға бағасы емес.

Тексерулерді жөнелту белсенділігі мен бизнес тәуекеліне қарай жоспарлаңыз, rate limit талаптарын сақтаңыз және тапсырмалардың барлығы бір уақытта басталмауы үшін jitter қосыңыз. Қайталауға болатын сәтсіздіктер үшін шектелген backoff қолданыңыз және сервердің тиісті нұсқауларын орындаңыз. Тұрақты тіркелгі деректері немесе тексеру қателерін түзетпей қайта-қайта қайталамаңыз.

Практикалық гибридті жүйе күнделікті жаңартулар үшін вебхуктарды, ал күмәнді олқылықтар үшін мақсатты API оқуларын пайдаланады. Қабылдау сәтсіздіктерін, кезек жасын, өңдеу сәтсіздіктерін, қайталану деңгейін және салыстырып сәйкестендіру айырмашылықтарын бөлек бақылаңыз. Уақыт белгілері сенімді болса, дереккөздегі кідірісті вебхук жеткізу кідірісінен және ішкі өңдеу кідірісінен ажыратыңыз.

Жиі қойылатын сұрақтар

Қадағалау вебхуктары нақты уақыт режимінде жұмыс істей ме?

Олар келесі polling цикліне дейін күтуден туындайтын кідірісті азайта алады. Бірақ тасымалдаушының бірден сканерлеуіне немесе дереккөздің дереу жаңаруына кепілдік бермейді. Соңғы жаңалыққа тасымалдаушының хабарлауы, провайдердің өңдеуі, сұраудың жеткізілуі және өз қолданбаңыздың жұмысы кіреді.

Вебхуктарды қосқаннан кейін polling-ті толығымен тоқтатуға бола ма?

Провайдердің қалпына келу мүмкіндіктері мен бизнес талаптары мұны қолайлы етсе, мүмкін. Операциялық тұрғыдан маңызды жөнелту жазбалары үшін салыстырып сәйкестендіру әдісін сақтаңыз. Ол әр жөнелтуді үздіксіз polling етудің орнына мақсатты болуы мүмкін.

Вебхук endpoint-ім офлайн болса не болады?

Қалпына келу жіберушінің құжатталған қайталап жіберу саясатына тәуелді. Қайталап жіберу шексіз жалғасады деп болжамаңыз. Endpoint-ті қалпына келтіргеннен кейін сәтсіз жеткізулерді тексеріңіз, қолдау көрсетілетін қайта жеткізу құралдарын пайдаланыңыз және қолжетімді болса, API арқылы зардап шеккен жөнелтулерді салыстырып сәйкестендіріңіз.

Әр вебхук тұтынушыға хабарлама жіберуді іске қосуы керек пе?

Жоқ. Оқиға қайталанатын, тарихи бақылау нүктесі немесе тұтынушыға көрсетілетін мәртебені өзгертпейтін жаңарту болуы мүмкін. Хабарламаларды ерекшеліктер мен түзетулерге арналған ережелері бар, қайталануы жойылған бизнес ауысуларынан іске қосыңыз.

Сәтті HTTP жауабы жөнелту жаңартуы аяқталды дегенді білдіре ме?

Міндетті емес. Асинхронды дизайнда бұл қабылдағыштың келісілген келісімшарт бойынша оқиғаны қабылдағанын білдіреді. Қабылданған сұрау сәтсіз жұмыс үдерісін жасырып қалмауы үшін өңдеудің аяқталуын және кейінгі хабарлама нәтижелерін бөлек бақылаңыз.

Дереккөздер

• RFC 9110: HTTP Semantics — өңдеуге қабылдау және Retry-After қоса алғанда, HTTP жауаптарының семантикасы.
• RFC 2104: HMAC—Keyed-Hashing for Message Authentication — қолтаңбаны тексеру нұсқауларында аталған HMAC құрылымы.
• GitHub Docs: Best practices for using webhooks — HTTPS, құпиялар, асинхронды өңдеу және жеткізу идентификаторлары жөніндегі жалпы инженерлік нұсқаулар; оның қызметке тән ережелері жөнелту провайдерінің әрекетін белгілемейді.
• 17TRACK Tracking API — 17TRACK қадағалау интеграциясын бағалаудың ресми бастапқы беті.
• 17TRACK API documentation — іске асыру талаптарына арналған провайдерге тән анықтамалық.