İzləmə webhook endpoint-i nə qaytarmalıdır? Status kodları, vaxt aşımı və yenidən cəhdlər?
A izləmə webhook endpoint-i hadisəni emal üçün qəbul etdikdən sonra sürətli və məqsədli 2xx cavabı qaytarmalıdır. Əksər inteqrasiyalarda ən təhlükəsiz yanaşma sorğunu autentifikasiya etmək, yükü yoxlamaq, hadisəni saxlamaq və ya növbəyə əlavə etmək, sonra isə 200 OK və ya 202 Accepted ilə təsdiqləməkdir. Göndəricinin yenidən cəhd etməməli olduğu sorğular üçün 4xx cavablarından, müvəqqəti server problemi qəbul etməyə mane olduqda isə 5xx cavablarından istifadə edin. Dəqiq timeout və yenidən cəhd davranışı webhook provayderinin müqaviləsindən asılıdır. Buna görə tətbiqiniz fərziyyələrə deyil, göndəricinin sənədləşdirilmiş davranışına əsasən hazırlanmalıdır.

İzləmə və ya göndəriş statusu webhook-u üçün bu fərq vacibdir, çünki çatdırılma hadisələri bir dəfədən çox, ardıcıllıqdan kənar və ya şəbəkə xətasından sonra yenidən göndərilə bilər. Endpoint-in vəzifəsi cavab verməzdən əvvəl mütləq hər bir biznes əməliyyatını tamamlamaq deyil. Onun ilk vəzifəsi hadisənin qəbul edilib-edilmədiyi barədə etibarlı qərar verməkdir.
Cavab müqaviləsi praktik baxımdan
Webhook cavabının iki auditoriyası var: göndərən sistem və sizin tətbiqiniz. Göndəriciyə çatdırılmanı uğurlu hesab edib-etməmək, yenidən cəhd etmək və ya dayandırmaq üçün aydın HTTP nəticəsi lazımdır. Tətbiqinizə isə hadisəni yoxlamaq və etibarlı şəkildə qeyd etmək üçün kifayət qədər vaxt lazımdır. Endpoint kiçik sinxron yol və ayrıca asinxron emal yolu ilə qurulduqda bu məqsədlərə çatmaq daha asandır.
- HTTP sorğusunu HTTPS üzərindən qəbul edin.
- Provayderin tələb etdiyi imzanı, autentifikasiya məlumatlarını, vaxt möhürünü və ya digər sorğu bütövlüyü nəzarətlərini yoxlayın.
- Aşağı axın əməliyyatlarını ləngitmədən yükü təhlil edin və yoxlayın.
- Hadisəni və ya deduplikasiya qeydini və hadisə istinadını etibarlı yaddaşda və ya etibarlı növbədə saxlayın.
- Məqsədli 2xx cavabı qaytarın.
- İzləmə yeniləməsini, müştəri bildirişini, inventar dəyişikliyini və ya digər biznes əməliyyatını asinxron şəkildə emal edin.
Hadisə yalnız proses yaddaşında mövcuddursa, cavab qəbul edildiyini bildirməməlidir. Uğurlu cavab qaytarıldıqdan dərhal sonra tətbiq çökərsə, heç vaxt saxlanılmamış hadisə itə bilər, halbuki göndərən çatdırılmanın uğurlu olduğuna inanır. Buna görə 2xx qaytardığınız məqam faktiki davamlılıq zəmanətinizə uyğun olmalıdır.
Webhook hansı status kodunu qaytarmalıdır?
| Cavab | Göndərici üçün mənası | Webhook-da tipik istifadə |
|---|---|---|
200 OK | Sorğu qəbul edildi və uğurla emal olundu. | Yoxlamadan və etibarlı qəbuldan sonra praktik standart seçim. |
202 Accepted | Sorğu emal üçün qəbul edildi, lakin iş davam edə bilər. | Hadisə təhlükəsiz şəkildə növbəyə əlavə edildikdə, biznes emalı asinxron olduqda faydalıdır. |
204 No Content | Sorğu uğurlu oldu və cavab gövdəsi tələb olunmur. | Provayder boş uğur cavabını qəbul etdikdə uyğundur. |
400–499 | Sorğu yanlışdır, icazəsizdir və ya göndərildiyi formada qəbul edilə bilməz. | Qüsurlu yük, uğursuz autentifikasiya, yanlış imza və ya həmişəlik rədd edilmiş hadisə. |
429 Too Many Requests | Qəbul edən tərəf sürət məhdudiyyəti tətbiq edir. | Yalnız göndəricinin yenidən cəhd davranışı və sürət məhdudiyyəti siyasətiniz uyğun olduqda istifadə edin. |
500–599 | Server tərəfli və ya müvəqqəti problem səbəbindən qəbul edən tərəf sorğunu qəbul edə bilmədi. | Verilənlər bazasının dayanması, növbə xətası, asılılıq xətası və ya gözlənilməz tətbiq xətası. |
200 OK çox vaxt ən az təəccüb doğuran seçimdir, çünki uğurlu qəbul kimi geniş şəkildə başa düşülür. Endpoint hadisəni sonrakı emal üçün qəbul etdikdə 202 Accepted də məna baxımından faydalıdır. Heç bir kod avtomatik olaraq düzgün deyil: göndəricinin sənədləri hansı 2xx cavablarının uğurlu sayıldığını müəyyən edə bilər və bəzi provayderlər xüsusi gövdə və ya məzmun tipini gözləyə bilər.
HTTP sorğusu serverinizə çatdığı üçün sadəcə 2xx cavabı qaytarmayın. İmza yoxlaması uğursuz olarsa və ya yük təhlükəsiz şəkildə şərh edilə bilməzsə, 4xx cavabı adətən daha doğrudur. Əksinə, hadisə sonradan uğurlu ola bilərsə, müvəqqəti verilənlər bazası xətası üçün 4xx qaytarmayın. 5xx cavabı yenidən cəhd edə bilən göndəriciyə hadisəni yenidən çatdırmaq imkanı verir, baxmayaraq ki, provayder öz siyasətini tətbiq edə bilər.
Timeout-lar necə idarə edilməlidir?
Webhook timeout dəyərləri provayderə xasdır. Hər bir izləmə platformasının istifadə etdiyi universal HTTP timeout yoxdur və göndərici tətbiqiniz yavaş əməliyyatı tamamlamadan gözləməyi dayandıra bilər. Göndəricinin sənədləşdirilmiş timeout-unu hədəf deyil, maksimum sərhəd kimi qəbul edin. Endpoint normalda həmin sərhəddən xeyli əvvəl cavab verməlidir.
Ən geniş yayılmış dizayn səhvi webhook-u təsdiqləməzdən əvvəl bütün aşağı axın əməliyyatlarını yerinə yetirməkdir. Handler ardıcıllıqla verilənlər bazasına, sifariş idarəetmə sisteminə, bildiriş xidmətinə və analitika konveyerinə müraciət edə bilər. Bir yavaş asılılıq tətbiqiniz işi sonunda tamamladığı halda belə göndəricinin timeout görməsinə səbəb ola bilər. Bundan sonra göndərici yenidən cəhd edə və təkrar emal və ya bir-biri ilə ziddiyyət təşkil edən yeniləmələr yarada bilər.
Sinxron yolu yalnız təhlükəsiz qəbul qərarı vermək üçün lazım olan işlərlə məhdudlaşdırın. Buraya adətən sorğunun autentifikasiyası, əsas sxem yoxlaması, hadisənin etibarlı saxlanması və növbəyə dərc edilməsi daxildir. Bahalı zənginləşdirməni, daşıyıcı axtarışlarını, müştəri mesajlarını və üçüncü tərəf API çağırışlarını worker arxasına yerləşdirin. Hadisənin qəbul edilməsi, yoxlanması, saxlanması və təsdiqlənməsi üçün sərf olunan vaxtı onun emal vaxtından ayrıca izləyin.
Timeout uğursuz biznes əməliyyatı ilə eyni deyil. Göndəricinin nöqteyi-nəzərindən timeout adətən istifadə edilə bilən uğur cavabı almadığı deməkdir. Bağlantı bağlanmazdan əvvəl xidmətiniz hadisəni uğurla saxlamış ola bilər. Buna görə endpoint etibarlı görünsə belə, idempotentlik və deduplikasiya tələb olunur.
Yenidən cəhdlərə nə səbəb olur?
Webhook göndəricisi bağlantı xətasından, timeout-dan və ya müqaviləsinə görə uğursuz saydığı cavabdan sonra yenidən cəhd edə bilər. Dəqiq cədvəl, maksimum cəhd sayı, gecikmə alqoritmi və çatdırılma pəncərəsi provayderə görə dəyişir. Provayderin sənədlərində göstərilmədiyi halda sabit sayda yenidən cəhd vəd etməyin.
Qəbul edən tərəf yenidən cəhdlərin baş verə biləcəyini qəbul etməli və sistemi buna məqsədli şəkildə hazırlamalıdır:
- Mümkün olduqda hadisə identifikatorundan istifadə edin. Onu unikal məhdudiyyətlə və ya ekvivalent deduplikasiya açarı ilə saxlayın.
- Emalı idempotent edin. Eyni çatdırılma statusu yeniləməsinin iki dəfə tətbiqi iki müştəri mesajı göndərməməli, iki geri ödəniş yaratmamalı və sifarişi yanlış şəkildə irəlilətməməlidir.
- İlkin yükü və ya faydalı audit qeydini saxlayın. Bu, təkrar oynatma, araşdırma və uzlaşdırmanı dəstəkləyir.
- Qəbulu emaldan ayırın. Worker daxili xətaları yenidən sınaya bilər və göndəricini bütün HTTP mübadiləsini təkrarlamağa məcbur etməz.
- Cavab kodlarını və gecikməni qeyd edin. 5xx cavablarının, timeout-ların və ya təkrarlanan hadisə identifikatorlarının artması istifadəçilər çatışmayan izləmə yeniləmələrini bildirməzdən əvvəl kəsintini göstərə bilər.
Təkrarlanan hadisə ilkin hadisə artıq etibarlı şəkildə qəbul edilibsə, adətən uğurlu cavab almalıdır. Hər bir təkrara xəta qaytarmaq lazımsız yenidən cəhdlərə səbəb ola bilər. Endpoint hadisənin əvvəllər görüldüyünü qeyd edə, təkrarlanan biznes əməliyyatını ötürə və yeni qəbul edilmiş hadisə üçün istifadə olunan eyni uğur sinfini qaytara bilər.
4xx, 429 və ya 5xx nə vaxt qaytarılmalıdır?
Eyni sorğunu yenidən göndərməyin problemi həll etməsi ehtimalı azdırsa, 4xx qaytarın. Buna yanlış imza, tələb olunan autentifikasiyanın olmaması, dəstəklənməyən yük forması və ya daimi yoxlama qaydasını pozan sorğu nümunədir. 4xx seçməzdən əvvəl göndəricinin bu statusu daimi uğursuzluq kimi qəbul edib-etmədiyini yoxlayın. Bəzi platformaların uğursuz çatdırılmalar üçün öz qaydaları var.
429-dan diqqətlə istifadə edin. HTTP sürət məhdudiyyəti üçün 429-u müəyyən edir və Retry-After başlığı yenidən cəhdin nə vaxt uyğun ola biləcəyini bildirə bilər. Lakin bütün webhook göndəriciləri 429-u eyni şəkildə şərh etmir. Növbəniz doludursa və ya xidmətiniz həddən artıq yüklənibsə, provayderin təhlükəsiz şəkildə yenidən cəhd edəcəyini və cədvəlin yüklənməni artırmayacağını təsdiqləyin. Məhdudlaşdırılmış qəbul növbəsi və geri təzyiq planı sorğuların gözlənilməz şəkildə uğursuz olmasına imkan verməkdən adətən daha yaxşıdır.
Müvəqqəti problem səbəbindən qəbul edən tərəf hadisəni təhlükəsiz şəkildə qəbul edə bilmədikdə 5xx qaytarın. Buna əlçatmaz verilənlər bazası, etibarlı növbəyə yazma xətası və ya yoxlamaya və ya saxlanmaya mane olan daxili xəta daxildir. Hadisəni səssizcə itirərək 200 qaytarmaq bərpanı çətinləşdirir, çünki göndəricinin yenidən cəhd etməsi üçün səbəb qalmır.
Webhook çatdırılması üçün 301, 302 və ya 307 kimi yönləndirmələrə arxalanmayın. Yönləndirmənin idarə edilməsi müştərilər arasında fərqlənir və imzalanmış sorğunun yönləndirilməsi təyinat, metod və gövdə ilə bağlı qeyri-müəyyənlik yarada bilər. Bunun əvəzinə provayderi son HTTPS endpoint-i ilə konfiqurasiya edin.
İzləmə hadisələri üçün etibarlı cavab siyasəti
Əksər izləmə webhook inteqrasiyaları üçün aşağıdakı siyasət məntiqli başlanğıcdır:
- Hadisə autentifikasiyadan keçdikdən və etibarlı şəkildə saxlanıldıqdan və ya etibarlı növbəyə yerləşdirildikdən sonra
200və ya202qaytarın. - Provayderin sənədləşdirilmiş qaydalarına uyğun olaraq yanlış imza, yanlış autentifikasiya və ya daimi olaraq istifadəyə yararsız yük üçün 4xx cavabı qaytarın.
- Müvəqqəti xəta etibarlı qəbula mane olduqda 5xx qaytarın.
- Təhlükəsiz şəkildə tanınan təkrar hadisə üçün uğurlu cavab qaytarın və təkrarlanan biznes təsirlərinin qarşısını alın.
- Handler-i sürətli saxlayın və onun təsdiqləmə gecikməsini ölçün.
- İstehsala buraxmazdan əvvəl timeout, yenidən cəhd, təkrar, ardıcıllıqdan kənar, qüsurlu və provayderin dayanması ssenarilərini yoxlayın.
İzləmə API-si inteqrasiya edirsinizsə, provayderin webhook sənədlərindən başlayın və qəbul edilən uğur kodlarını, sorğunun imzalanma metodunu, timeout-u, yenidən cəhd şərtlərini, yük sxemini və hadisə identifikatorunu təsdiqləyin. 17TRACK inteqrasiyaları üçün provayderə xas müqaviləni ümumi HTTP praktikasından çıxarmaq əvəzinə yoxlamaq üçün rəsmi Tracking API sənədləri uyğun mənbədir.
Tətbiq yoxlama siyahısı
- Endpoint HTTPS üzərindən əlçatandır və sabit istehsal URL-inə malikdir.
- Autentifikasiya və imza yoxlaması biznes emalından əvvəl aparılır.
- Xam sorğu və ya yoxlanıla bilən təqdimat imza yoxlamaları və problemlərin araşdırılması üçün tələb olunduqda saxlanılır.
- Uğur cavabı göndərilməzdən əvvəl hadisə saxlanılır.
- Təkrar çatdırılmalar təhlükəsizdir və geri dönməz əməliyyatları təkrarlamır.
- Worker-lər göndəricinin HTTP yenidən cəhd dövründən asılı olmayaraq daxili emalı yenidən sınaya bilir.
- Qeydlərə sirləri açıqlamadan hadisə ID-si, çatdırılma vaxtı, cavab kodu, emal vəziyyəti və korrelyasiya ID-si daxil edilir.
- Xəbərdarlıqlar endpoint timeout-larını, 4xx yoxlama xətalarını, 5xx kəsintilərini, növbə gecikmələrini və təkrar çatdırılmaları fərqləndirir.
- Sənədləşdirilmiş provayder davranışı real və ya sandbox hadisələri ilə yoxlanılıb.
FAQ
Webhook üçün 200 OK, yoxsa 202 Accepted daha yaxşıdır?
Heç biri universal olaraq daha yaxşı deyil. Sorğu qəbul edilibsə və inteqrasiyanız cavabı ümumi uğur kimi qəbul edirsə, 200 OK istifadə edin. Hadisə asinxron emal üçün qəbul edilibsə, 202 Accepted istifadə edin. Göndəricinin seçilmiş 2xx cavabını uğurlu kimi təsnif etdiyini təsdiqləyin.
Webhook endpoint-i izləmə yeniləməsi tam emal edilənə qədər gözləməlidirmi?
Adətən xeyr. O, yalnız hadisə autentifikasiya edildikdə, yoxlandıqda və etibarlı şəkildə qəbul edildikdə gözləməlidir. Uzunmüddətli iş adətən təsdiqdən sonra baş verməlidir ki, yavaş asılılıq qarşısı alına bilən timeout və yenidən cəhdə səbəb olmasın.
Eyni izləmə hadisəsi iki dəfə gəldikdə nə baş verməlidir?
Provayderin hadisə ID-si və ya diqqətlə hazırlanmış ekvivalent açardan istifadə edərək onu tanıyın, təkrar yan təsirləri ötürün və hadisə artıq qəbul edilibsə uğur cavabı qaytarın. Bu, yeni emal xətalarını gizlətmədən yenidən cəhdləri təhlükəsiz edir.
Yanlış imza 400, yoxsa 401 qaytarmalıdır?
Seçim autentifikasiya modelinizdən və provayderin sənədləşdirilmiş gözləntilərindən asılıdır. Hər ikisi rəddi bildirə bilər, lakin birini universal olaraq seçməkdənsə ardıcıllıq daha vacibdir. Həqiqiliyini yoxlaya bilmədiyiniz hadisəni təsdiqləməyin.
5xx cavabı həmişə yenidən cəhdə səbəb olurmu?
Xeyr. Bir çox webhook sistemi timeout-lardan və server xətalarından sonra yenidən cəhd edir, lakin yenidən cəhd şərtləri və cədvəlləri provayderə xasdır. Yenidən cəhdləri sənədləşdirilmiş inteqrasiya davranışı kimi qəbul edin və onları test mühitində yoxlayın.
Mənbələr
- RFC 9110: HTTP Semantics — uğurlu, müştəri xətası, server xətası, yönləndirmə və cavabların idarə edilməsi üçün təriflər.
- RFC 6585: Additional HTTP Status Codes —
429 Too Many Requestsspesifikasiyası. - Stripe Webhooks Documentation — webhook cavabları, asinxron emal və təkrar hadisələrin idarə edilməsi üzrə praktik təlimat.
- GitHub Docs: Handling Webhook Deliveries — webhook inteqrasiyaları üçün çatdırılmanın yoxlanması və əməliyyat mülahizələri.
- 17TRACK Tracking API Documentation — izləmə API-si inteqrasiyalarını tətbiq edərkən yoxlanmalı provayderə xas sənədlər.


