Webhook ilə göndərişlərin izlənməsi: İzləmə webhook-ları Polling ilə müqayisədə necə işləyir (Payload-lar, təkrar cəhdlər və quraşdırma)

Göndəriş izləmə vebhukları izləmə xidmətinin bildiriləsi yeniliyi olduqda tətbiqinizə HTTP sorğusu göndərir. Sorğulama əks istiqamətdə işləyir: tətbiqiniz ən son izləmə məlumatını təkrar-təkrar soruşur. Göndəriş məlumatlarını sifariş idarəetmə sisteminə, mağazaya və ya müştəri bildiriş xidmətinə qoşan tərtibatçılar üçün vebhuklar, dəstəkləndikdə, ümumiyyətlə əsas yeniləmə mexanizmi kimi daha yaxşı seçimdir; məqsədli sorğulama buraxılmış yeniləmələri bərpa etməyə və qeydləri uzlaşdırmağa kömək edə bilər.

Heç bir üsul daşıyıcının bağlamanı daha tez skan etməsini təmin etmir. Hər ikisi izləmə mənbəyinin yeni məlumatı nə vaxt qəbul edib təqdim etməsindən asılıdır. Praktik fərq tətbiqinizin bu məlumatı necə öyrənməsində, nə qədər sorğu trafiki yaratmasında və çatdırılma uğursuz olduqda nə baş verməsindədir.

İzləmə vebhukları və sorğulama: əməliyyat fərqi

Bunlar rəqabət aparan izləmə verilənlər bazaları deyil, inteqrasiya nümunələridir. Daşıyıcı və ya izləmə platforması müxtəlif giriş şərtləri ilə bu nümunələrdən birini və ya hər ikisini təklif edə bilər. Bütün vebhuk xidmətlərinin eyni təminatlara malik olduğunu düşünmək əvəzinə istifadə etməyi planlaşdırdığınız konkret API-nin davranışını müqayisə edin.

Əvvəlcə vebhukları seçin — vaxtında yeniləmələr vacibdirsə və komandanız etibarlı qəbul edicini işlədə bilirsə. Əvvəlcə sorğulamayı seçin — daxil olan son nöqtələr praktik deyilsə, göndəriş həcmi azdırsa və ya mənbə uyğun vebhuklar təqdim etmirsə. Hibrid dizayndan istifadə edin — buraxılmış yeniləmələr müştəri kommunikasiyasını və ya əməliyyatları poza bilərsə və API uzlaşdırmanı dəstəkləyirsə.

Vebhukların daha ucuz olduğunu düşünməyin. Abunə ödənişləri, izləmənin qeydiyyatı, API çağırışları, hadisələrin çatdırılması və infrastruktur müxtəlif qaydada hesablandırıla bilər. Daha az sorğunu aşağı hesabın sübutu kimi qəbul etmək əvəzinə faktiki kommersiya şərtlərini və gözlənilən iş yükünü müqayisə edin.

Daşıyıcının skanı ilə tətbiqiniz arasında nə baş verir?

1. Göndərişi müəyyənləşdirin. İzləmə nömrəsini, tələb olunduqda daşıyıcı məlumatlarını və daxili göndəriş istinadını əlaqələndirin. Bəzi xidmətlər monitorinq başlamazdan əvvəl qeydiyyat tələb edir.
2. Hadisə çatdırılmasını konfiqurasiya edin. HTTPS geri çağırış URL-i təqdim edin və dəstəklənən hadisə abunəliklərini seçin.
3. Mənbə izləmə məlumatını qəbul edir. Daşıyıcı skanı və ya status dəyişikliyi izləmə xidməti üçün əlçatan olur.
4. Xidmət vebhuk göndərir. Sorğuda tam izləmə görüntüsü, bir yoxlama nöqtəsi və ya API axtarışı tələb edən yalnız istinad ola bilər.
5. Qəbul ediciniz onu yoxlayır və saxlayır. Sorğunu autentifikasiya edin, strukturunu yoxlayın və hadisəni davamlı şəkildə qeyd edin və ya növbəyə əlavə edin.
6. İşçi biznes sistemlərini yeniləyir. Statusları normallaşdırın, göndəriş qeydlərini yeniləyin və yalnız hələ uyğun olan əməliyyatları başladın.

Vebhuk çatdırılması fiziki çatdırılma ilə eyni deyil. Bu, göndəriş məlumatı haqqında mesajdır. Eynilə, uğurlu vebhuk cavabı e-poçtun göndərildiyini və ya sifariş qeydinin yeniləndiyini sübut etmir; bunlar ayrıca monitorinq tələb edən sonrakı emal nəticələridir.

İzləmə vebhuk yükünün oxunması

Aşağıdakı JSON 17TRACK yükü və ya universal sxem deyil, nümunəvi inteqrasiya dizaynıdır. Həqiqi sahə adları, status kodları, vaxt möhürü formatları və hadisə identifikatorları seçilmiş təchizatçının sənədlərindən götürülməlidir.

{
  "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"
    }
  }
}

Məlumat modelinizdə üç saatı ayırın: göndəriş hadisəsinin baş verdiyi vaxt, təchizatçının mesajı yaratdığı vaxt və tətbiqinizin onu qəbul etdiyi vaxt. Gecikmiş yoxlama nöqtəsi daha yenisindən sonra gələ bilər. Ofseti olmayan vaxt möhürü dəqiq şərh tələb edir; hər daşıyıcının yerli vaxtını səssizcə UTC kimi qəbul etməyin.

Daxili göndəriş istinadınızı təchizatçının identifikatorları ilə birlikdə saxlayın. Xüsusilə müxtəlif daşıyıcı kontekstlərində izləmə nömrəsi daimi qlobal identifikator kimi kifayət etməyə bilər. Bölünmüş sifarişlər üçün bir bağlamanın çatdırılmış statusunun bütün sifarişi tamamlanmış kimi işarələməsinə imkan vermək əvəzinə göndəriş səviyyəsində qeydlər saxlayın.

Orijinal statusu və təsviri normallaşdırılmış biznes statusunuzla yanaşı qoruyun. Tətbiqiniz bir neçə daşıyıcı mesajını “in transit” kimi xəritələndirə bilər, lakin dəstək əməkdaşlarına gecikməni anlamaq üçün orijinal yoxlama nöqtəsi lazım ola bilər. Təxmini çatdırılma tarixlərini təxmin kimi qəbul edin və çatışmayan sahə ilə mövcud dəyərin silinməsi barədə açıq göstərişi fərqləndirin.

Təkrar cəhdlər, təsdiqlər və dublikat hadisələr

Vebhuk çatdırılması vaxt aşımı, şəbəkə kəsintiləri, autentifikasiya xətaları və ya əlçatmaz qəbul edici səbəbindən uğursuz ola bilər. Təchizatçı yenidən cəhd edə bilər, lakin universal təkrar cəhd cədvəli, saxlama müddəti və ya maksimum cəhd sayı yoxdur. Hansı cavabların növbəti cəhdi işə saldığını, yönləndirmələrin necə idarə olunduğunu və əl ilə yenidən çatdırmanın mümkün olub-olmadığını təsdiqləyin.

Davamlı qəbuldan sonra təsdiqləyin

Sorğu yolunu qısa saxlayın: sorğunu yoxlayın, qəbul edilmiş işi davamlı şəkildə saxlayın və təchizatçının tələb etdiyi uğur cavabını qaytarın. E-poçt göndərilməsini və daha yavaş biznes əməliyyatlarını asinxron icra edin. HTTP spesifikasiyası 202 Accepted kodunu tamamlanmış emal deyil, emal üçün qəbul kimi müəyyən edir, lakin təchizatçınız başqa uğur cavabı tələb edə bilər. Onun vebhuk müqaviləsinə əməl edin.

Heç nə saxlamadan əvvəl uğur qaytarmaq prosesiniz çökərsə yeniləmənin itirilməsi riskini yaradır. Hər sonrakı əməliyyatı gözləmək isə vaxt aşımı və başqa çatdırılma cəhdi riski yaradır. Davamlı inbox və ya növbə qəbul ilə emal arasında sərhəd yaradır.

Emalı idempotent edin

İdempotentlik eyni hadisənin yenidən emalının biznes təsirlərini təkrarlamaması deməkdir. Göndərən serveriniz hadisəni qəbul etdikdən, lakin təsdiq itdikdən sonra yenidən cəhd edə bilər. Buna görə dublikat çatdırılma adi test nümunəsi olmalıdır.

• Mövcud olduqda sənədləşdirilmiş hadisə identifikatorundan düzgün təchizatçı və ya hesab çərçivəsində deduplikasiya açarı kimi istifadə edin.
• İdentifikator yoxdursa, sabit hadisə sahələrindən kompozit açar yaradın və toqquşma risklərini test edin.
• Saxlamada unikallığı atomik şəkildə təmin edin; ayrıca “yoxla, sonra əlavə et” ardıcıllığı paralel çatdırılma zamanı yarışa səbəb ola bilər.
• Sonrakı əməliyyatları da qoruyun. Dublikat hadisə başqa çatdırılma bildirişi göndərməməli və maliyyə əməliyyatını təkrarlamamalıdır.
• Saxlama müddətini təchizatçının təkrar oynatma davranışına və bərpa tələblərinizə uyğun müəyyən edin; deduplikasiya qeydlərini dərhal silməyin.

Xronoloji gəlişi fərz etməyin

Sorğu sonuncu gəldi deyə cari göndəriş vəziyyətinin üzərinə yazmayın. Hadisənin mənasını, vaxt möhürlərini və sənədləşdirilmiş ardıcıllıq məlumatlarını müqayisə edin. Gecikmiş yoxlama nöqtələrini tarixçədə qoruyun və göstərilən statusu avtomatik olaraq geriyə çəkməyin. Eyni zamanda sənədləşdirilmiş düzəlişlərə icazə verin: çatdırılmış göndərişlərin heç vaxt dəyişə bilməyəcəyini bildirən sərt qayda qanuni istisnaları və ya düzəldilmiş məlumatları gizlədə bilər.

Praktik quraşdırma yoxlama siyahısı

1. Təchizatçı müqaviləsini təsdiqləyin

Tətbiqdən əvvəl qeydiyyat tələblərini, dəstəklənən hadisələri, yük strukturunu, autentifikasiyanı, cavab gözləntilərini, vaxt aşımlarını, təkrar cəhd davranışını və API limitlərini təsdiqləyin. Bildirişin görüntü, yoxsa artımlı dəyişiklik olduğunu, çatdırılmaların bir neçə qeyd ehtiva edə bilib-bilmədiyini və abunəliyin ilkin vəziyyəti göndərib-göndərmədiyini yoxlayın.

17TRACK inteqrasiyası üçün rəsmi Tracking API page və API documentation səhifələrindən başlayın. Sorğu sahələrini və geri çağırış tələblərini müəyyən etmək üçün təchizatçıya xas sənədlərdən istifadə edin; yuxarıdakı ümumi yük bunun əvəzi deyil. Yerləşdirməyi planlaşdırdığınız inteqrasiya üçün giriş şərtlərini və əməliyyat limitlərini təsdiqləyin.

2. Qəbul edən son nöqtəni qoruyun

HTTPS və təchizatçının sənədləşdirdiyi autentifikasiya mexanizmindən istifadə edin. HMAC imzasından istifadə edirsə, onun göstərdiyi imzalanmış girişi dəqiq yoxlayın. Xam sorğu baytları imzalanırsa, yoxlamadan əvvəl JSON-u təhlil edib yenidən seriyalaşdırmaq həmin baytları dəyişə və imzanı etibarsız edə bilər. Məxfi məlumatdan törədilmiş imza dəyərlərini sabit vaxtlı müqayisə ilə yoxlayın.

İmzalanmış vaxt möhürləri və ya çatdırılma identifikatorları mövcuddursa, sənədləşdirilmiş təkrar oynatma nəzarətlərini tətbiq edin. Etibarlı imza mesajı autentifikasiya edir, lakin öz-özlüyündə onun yeni olduğunu təsdiqləmir. Məxfi məlumatları URL-lərdən və tətbiq jurnallarından uzaq saxlayın, məxfi məlumatların rotasiyasını dəstəkləyin və sorğu ölçülərini məhdudlaşdırın. IP icazə siyahısı saxlanılan ünvan diapazonları olduqda əlavə nəzarət ola bilər, lakin mesaj autentifikasiyasını əvəz etmir.

3. Qəbulu biznes emalından ayırın

Qəbul edilmiş hadisəni izləmək və təhlükəsiz şəkildə yenidən oynatmaq üçün kifayət qədər məlumat saxlayın. Növbə işçiləri yeniləməni normallaşdırmalı, vəziyyət keçidi qaydalarını tətbiq etməli və əməliyyat nəticələrini qeyd etməlidir. Davamlı uğursuz olan işləri sonsuz təkrar cəhd etmək əvəzinə nəzərdən keçirilə bilən dead-letter prosesinə yönləndirin. İzləmə yüklərində müştəri ilə bağlı məlumat ola bildiyi üçün giriş və saxlama müddətini məhdudlaşdırın.

4. İşə salınmazdan əvvəl uğursuzluq yollarını test edin

• Eyni hadisəni paralel çatdırılmalar da daxil olmaqla iki dəfə göndərin.
• Daha yenisindən sonra köhnə yoxlama nöqtəsini çatdırın.
• Növbə kəsintisini və qəbuldan sonra işçinin çökməsini simulyasiya edin.
• Yanlış autentifikasiyanı, səhv formatlı JSON-u və həddindən artıq böyük sorğuları test edin.
• Naməlum göndərişləri, çatışmayan əlavə sahələri və əlavə edilmiş sahələri test edin.
• Bir çatdırılmış bağlamanın bölünmüş sifarişi tamamlamadığını yoxlayın.
• Bərpadan sonra hadisəni yenidən oynadın və bildirişlərin deduplike olaraq qaldığını təsdiqləyin.

Təhlükəsiz olduğu hallarda əlavə sahələrə tolerant yanaşın, lakin naməlum status dəyərlərini səssizcə yenidən şərh etməyin. Xam dəyəri qoruyun və tanınmayan halları müəyyən edilmiş ehtiyat və ya nəzərdən keçirmə prosesinə yönləndirin.

Sorğulamanın hələ də faydalı olduğu hallar

Sorğulama ilkin sinxronizasiya, kəsintidən sonra bərpa və gözlənilən yeniləmələri gəlməyən göndərişlərin yoxlanılması üçün faydalıdır. Lakin təkcə səssizlik vebhuk uğursuzluğunun sübutu deyil: bağlamanın həqiqətən yeni skanı olmaya bilər. Hər sakit göndərişin xəbərdarlığa ehtiyacı olduğunu düşünmək əvəzinə API-nin cari vəziyyəti və ya tarixçəsi ilə uzlaşdırın.

Miqyas planlaması üçün sadələşdirilmiş sorğulama modeli belədir: requests per hour ≈ active shipments × polls per shipment per hour; burada hər sorğuda bir göndəriş nəzərdə tutulur. Qrup son nöqtələri bu hesablamanı dəyişir. Nümunə olaraq, 1,000 göndərişin saatda dörd dəfə yoxlanılması təkrar cəhdlərdən əvvəl saatda 4,000 sorğu yaradır; bu, hesablamadır, təchizatçı kvotası və ya qiymət təxmini deyil.

Yoxlamaları göndəriş aktivliyinə və biznes riskinə uyğun planlaşdırın, sürət limitlərinə riayət edin və işlərin hamısının eyni vaxtda başlamaması üçün təsadüfi gecikmə əlavə edin. Təkrar cəhd edilə bilən uğursuzluqlar üçün məhdudlaşdırılmış geriçəkilmədən istifadə edin və tətbiq olunan server göstərişlərinə əməl edin. Daimi etimadnamə və ya yoxlama xətalarını düzəltmədən təkrar-təkrar yoxlamayın.

Praktik hibrid sistem adi yeniləmələr üçün vebhuklardan, ehtimal olunan boşluqlar üçün isə məqsədli API oxunuşlarından istifadə edir. Qəbul uğursuzluqlarını, növbə yaşını, emal uğursuzluqlarını, dublikat dərəcələrini və uzlaşdırma uyğunsuzluqlarını ayrıca monitorinq edin. Vaxt möhürləri etibarlıdırsa, mənbə məlumatı gecikməsini vebhuk çatdırılması gecikməsindən və daxili emal gecikməsindən fərqləndirin.

FAQ

İzləmə vebhukları real vaxt rejimindədirmi?

Onlar növbəti sorğulama dövrünü gözləməkdən yaranan gecikməni azalda bilər. Lakin ani daşıyıcı skanlarına və ya mənbənin dərhal yenilənməsinə zəmanət vermirlər. Başdan-başa aktuallığa daşıyıcının hesabatı, təchizatçının emalı, sorğunun çatdırılması və sizin tətbiqiniz daxildir.

Vebhukları aktiv etdikdən sonra sorğulamaya tamamilə son verə bilərəmmi?

Təchizatçının bərpa xüsusiyyətləri və biznes tələbləriniz bunu məqbul edirsə, mümkündür. Əməliyyat baxımından vacib göndəriş qeydləri üçün uzlaşdırma üsulunu saxlayın. Bu, hər göndərişin davamlı sorğulanması əvəzinə məqsədli ola bilər.

Vebhuk son nöqtəm oflayn olarsa nə baş verir?

Bərpa göndərənin sənədləşdirilmiş təkrar cəhd siyasətindən asılıdır. Təkrar cəhdlərin sonsuza qədər davam etdiyini düşünməyin. Son nöqtəni bərpa etdikdən sonra uğursuz çatdırılmaları yoxlayın, dəstəklənən yenidən çatdırma vasitələrindən istifadə edin və mümkün olduqda təsirlənmiş göndərişləri API vasitəsilə uzlaşdırın.

Hər vebhuk müştəri bildirişini işə salmalıdırmı?

Xeyr. Hadisə dublikat, tarixi yoxlama nöqtəsi və ya müştəriyə göstərilən statusu dəyişdirməyən yeniləmə ola bilər. Bildirişləri istisnalar və düzəlişlər üçün qaydalarla birlikdə deduplike edilmiş biznes keçidlərindən başladın.

Uğurlu HTTP cavabı göndəriş yeniləməsinin tamamlandığını bildirirmi?

Mütləq deyil. Asinxron dizaynda bu, qəbul edicinin razılaşdırılmış müqaviləyə əsasən hadisəni qəbul etdiyini bildirir. Qəbul edilmiş sorğunun uğursuz iş axınını gizlətməməsi üçün emalın tamamlanmasını və sonrakı bildiriş nəticələrini ayrıca izləyin.

Mənbələr

• RFC 9110: HTTP Semantics — emal üçün qəbul və Retry-After daxil olmaqla HTTP cavab semantikası.
• RFC 2104: HMAC—Keyed-Hashing for Message Authentication — imza yoxlaması təlimatlarında istinad edilən HMAC konstruksiyası.
• GitHub Docs: Best practices for using webhooks — HTTPS, məxfi məlumatlar, asinxron emal və çatdırılmanın identifikasiyası ilə bağlı ümumi mühəndislik təlimatları; xidmətə xas qaydaları göndəriş təchizatçısının davranışını müəyyən etmir.
• 17TRACK Tracking API — 17TRACK izləmə inteqrasiyasını qiymətləndirmək üçün rəsmi giriş səhifəsi.
• 17TRACK API documentation — tətbiq tələbləri üçün təchizatçıya xas istinad.