Bir İzleme Webhook Uç Noktası Neyi Döndürmelidir? Durum Kodları, Zaman Aşımları ve Yeniden Denemeler?
Bir takip webhook uç noktası, olayı işlenmek üzere kabul ettikten sonra hızlı ve bilinçli bir 2xx yanıtı döndürmelidir. Çoğu entegrasyonda en güvenli yaklaşım; isteğin kimliğini doğrulamak, yükü doğrulamak, olayı depolamak veya kuyruğa almak ve 200 OK ya da 202 Accepted ile onaylamaktır. Gönderenin yeniden denememesi gereken istekler için 4xx yanıtlarını, geçici bir sunucu tarafı sorunu kabul işlemini engellediğinde ise 5xx yanıtlarını kullanın. Kesin zaman aşımı ve yeniden deneme davranışı yine de webhook sağlayıcısının sözleşmesine bağlıdır; bu nedenle uygulamanız varsayımlara değil, belgelenmiş gönderen davranışına göre tasarlanmalıdır.
Bir takip veya gönderi durumu webhook'u için bu ayrım önemlidir; çünkü teslimat olayları birden fazla kez, sırası dışında veya ağ arızasından sonra yeniden oynatılarak gelebilir. Uç noktanın görevi, yanıt vermeden önce her iş operasyonunu tamamlamak zorunda değildir. İlk görevi, olayın kabul edilip edilmediğine ilişkin güvenilir bir karar vermektir.
Pratik açıdan yanıt sözleşmesi
Bir webhook yanıtının iki muhatabı vardır: gönderen sistem ve kendi uygulamanız. Gönderenin, teslimatı başarılı olarak işaretleyip işaretlemeyeceğine, yeniden deneyip denemeyeceğine veya durup durmayacağına karar verebilmesi için net bir HTTP sonucuna ihtiyacı vardır. Uygulamanızın ise olayı doğrulamak ve kalıcı olarak kaydetmek için yeterli zamana ihtiyacı vardır. Uç noktanın küçük bir senkron yol ve ayrı bir asenkron işleme yoluna sahip olması bu hedeflere ulaşmayı kolaylaştırır.
- HTTP isteğini HTTPS üzerinden alın.
- Sağlayıcının gerektirdiği imzayı, kimlik doğrulama bilgilerini, zaman damgasını veya diğer istek bütünlüğü kontrollerini denetleyin.
- Yavaş alt sistem işlemleri gerçekleştirmeden yükü ayrıştırın ve doğrulayın.
- Olayı ya da bir tekilleştirme kaydını ve olay referansını kalıcı depolamaya veya güvenilir bir kuyruğa yazın.
- Bilinçli bir 2xx yanıtı döndürün.
- Takip güncellemesini, müşteri bildirimini, envanter değişikliğini veya diğer iş işlemlerini asenkron olarak gerçekleştirin.
Bir olay yalnızca işlem belleğinde bulunuyorsa yanıt kabul edildiğini iddia etmemelidir. Uygulama başarı döndürdükten hemen sonra çökerse, kalıcılaştırılmamış bir olay kaybolabilir ve gönderen teslimatın başarılı olduğuna inanabilir. Bu nedenle 2xx döndürdüğünüz nokta, gerçek dayanıklılık garantinizle örtüşmelidir.
Bir webhook hangi durum kodunu döndürmelidir?
| Yanıt | Gönderen açısından anlamı | Tipik webhook kullanımı |
|---|---|---|
200 OK | İstek kabul edildi ve başarıyla işlendi. | Doğrulama ve kalıcı kabul sonrasında pratik varsayılan seçimdir. |
202 Accepted | İstek işlenmek üzere kabul edildi, ancak işlem devam edebilir. | Olay güvenli biçimde kuyruğa alındığında ancak işleme asenkron olduğunda kullanışlıdır. |
204 No Content | İstek başarılı oldu ve yanıt gövdesi gerekli değil. | Sağlayıcı boş bir başarı yanıtını kabul ediyorsa uygundur. |
400–499 | İstek geçersiz, yetkisiz veya gönderildiği haliyle kabul edilemez. | Hatalı yük, başarısız kimlik doğrulama, geçersiz imza veya kalıcı olarak reddedilen olay. |
429 Too Many Requests | Alıcı hız sınırlaması uyguluyor. | Yalnızca gönderenin yeniden deneme davranışı ile hız sınırlama politikanız uyumluysa kullanın. |
500–599 | Alıcı, sunucu taraflı veya geçici bir sorun nedeniyle isteği kabul edemedi. | Veritabanı kesintisi, kuyruk hatası, bağımlılık hatası veya beklenmeyen uygulama hatası. |
200 OK çoğu zaman en az şaşırtıcı seçenektir; çünkü başarılı alım olarak geniş biçimde anlaşılır. Uç nokta olayı daha sonra işlenmek üzere kabul ettiğinde 202 Accepted de anlamsal olarak yararlıdır. Her iki kod da otomatik olarak doğru değildir: gönderenin belgeleri hangi 2xx yanıtlarının başarılı sayıldığını tanımlayabilir ve bazı sağlayıcılar belirli bir gövde veya içerik türü bekleyebilir.
HTTP isteği sunucunuza ulaştı diye yalnızca bu nedenle 2xx yanıtı döndürmeyin. İmza doğrulaması başarısızsa veya yük güvenli biçimde yorumlanamıyorsa 4xx yanıtı genellikle daha doğrudur. Bunun tersine, olay daha sonra başarılı olabilecekse geçici bir veritabanı kesintisi için 4xx döndürmeyin. 5xx yanıtı, yeniden denemeyi destekleyen bir gönderene olayı tekrar teslim etme fırsatı verir; ancak sağlayıcı kendi politikasını uygulayabilir.
Zaman aşımları nasıl ele alınmalıdır?
Webhook zaman aşımı değerleri sağlayıcıya özeldir. Her takip platformunun kullandığı evrensel bir HTTP zaman aşımı yoktur ve gönderen, uygulamanız yavaş bir işlemi tamamlamadan önce beklemeyi bırakabilir. Gönderenin belgelenmiş zaman aşımını hedef değil, azami sınır olarak değerlendirin. Uç noktanız normalde bu sınırdan çok önce yanıt vermelidir.
En yaygın tasarım hatası, webhook'u onaylamadan önce tüm alt sistem işlemlerini gerçekleştirmektir. Bir işleyici sırayla veritabanını, sipariş yönetim sistemini, bildirim hizmetini ve analiz hattını çağırabilir. Tek bir yavaş bağımlılık, uygulamanız sonunda işi tamamlamış olsa bile gönderenin zaman aşımı görmesine neden olabilir. Gönderen daha sonra yeniden deneyerek yinelenen işlemler veya çakışan güncellemeler oluşturabilir.
Senkron yolu yalnızca güvenli bir kabul kararı vermek için gereken işlemlerle sınırlı tutun. Bu genellikle istek kimlik doğrulamasını, temel şema doğrulamasını, kalıcı olay depolamasını ve kuyruğa yayınlamayı içerir. Maliyetli zenginleştirme işlemlerini, taşıyıcı sorgularını, müşteri mesajlarını ve üçüncü taraf API çağrılarını bir çalışan arkasına koyun. Olayı alma, doğrulama, kalıcılaştırma ve onaylama sürelerini, olayın işlenme süresinden ayrı olarak izleyin.
Zaman aşımı, başarısız bir iş operasyonuyla aynı şey değildir. Gönderen açısından zaman aşımı genellikle kullanılabilir bir başarı yanıtı almadığı anlamına gelir. Bağlantı kapanmadan hemen önce hizmetiniz olayı başarıyla depolamış olabilir. Bu nedenle uç nokta güvenilir görünse bile idempotensi ve tekilleştirme gereklidir.
Yeniden denemelere ne sebep olur?
Bir webhook göndereni bağlantı hatası, zaman aşımı veya sözleşmesinde başarısız olarak sınıflandırdığı bir yanıt sonrasında yeniden deneyebilir. Kesin zamanlama, azami deneme sayısı, geri çekilme algoritması ve teslimat penceresi sağlayıcıya göre değişir. Sağlayıcının belgelerinde belirtilmediği sürece sabit bir yeniden deneme sayısı taahhüt etmeyin.
Alıcı, yeniden denemelerin gerçekleşebileceğini varsaymalı ve sistemi buna göre tasarlamalıdır:
- Varsa bir olay tanımlayıcısı kullanın. Bunu benzersiz bir kısıtla veya eşdeğer bir tekilleştirme anahtarıyla saklayın.
- İşlemeyi idempotent hâle getirin. Aynı teslimat durumu güncellemesinin iki kez uygulanması iki müşteri mesajı göndermemeli, iki iade oluşturmamalı veya siparişi hatalı biçimde ilerletmemelidir.
- Orijinal yükü veya yararlı bir denetim kaydını koruyun. Bu, yeniden oynatma, inceleme ve mutabakatı destekler.
- Kabulü işlemeden ayırın. Bir çalışan, gönderenin tüm HTTP alışverişini tekrarlamasını gerektirmeden dahili hataları yeniden deneyebilir.
- Yanıt kodlarını ve gecikmeyi kaydedin. 5xx yanıtlarında, zaman aşımlarında veya yinelenen olay kimliklerinde artış olması, kullanıcılar eksik takip güncellemelerini bildirmeden önce bir kesintiyi ortaya çıkarabilir.
Özgün olay zaten kalıcı olarak kabul edilmişse yinelenen bir olay genellikle başarılı yanıt almalıdır. Her yinelenen olay için hata döndürmek gereksiz yeniden denemeleri tetikleyebilir. Uç nokta olayın daha önce görüldüğünü kaydedebilir, tekrarlanan iş eylemini atlayabilir ve yeni kabul edilen olay için kullanılan aynı başarı sınıfını döndürebilir.
4xx, 429 veya 5xx ne zaman döndürülmelidir?
Aynı isteği yeniden denemenin sorunu çözmesi olası değilse 4xx döndürün. Örnekler arasında geçersiz imza, gerekli kimlik doğrulamanın eksik olması, desteklenmeyen yük biçimi veya kalıcı bir doğrulama kuralını ihlal eden istek bulunur. 4xx seçmeden önce gönderenin bu durumu kalıcı hata olarak ele alıp almadığını kontrol edin. Bazı platformların başarısız teslimatlar için kendi kuralları vardır.
429'u dikkatli kullanın. HTTP, hız sınırlaması için 429'u tanımlar ve Retry-After başlığı yeniden denemenin ne zaman uygun olabileceğini bildirebilir. Ancak her webhook göndereni 429'u aynı şekilde yorumlamaz. Kuyruğunuz doluysa veya hizmetiniz aşırı yüklenmişse sağlayıcının güvenli biçimde yeniden deneyeceğini ve yeniden deneme zamanlamasının yükü artırmayacağını doğrulayın. Sınırlandırılmış bir alım kuyruğu ve geri basınç planı, isteklerin öngörülemez biçimde başarısız olmasına izin vermekten genellikle daha iyidir.
Geçici bir sorun nedeniyle alıcı olayı güvenli biçimde kabul edemediğinde 5xx döndürün. Buna kullanılamayan veritabanı, başarısız kalıcı kuyruk yazma işlemi veya doğrulamayı ya da kalıcılaştırmayı engelleyen dahili hata dahildir. Olayı sessizce düşürürken 200 döndürmek kurtarmayı zorlaştırır; çünkü gönderenin yeniden denemek için bir nedeni kalmaz.
Webhook teslimatı için 301, 302 veya 307 gibi yönlendirmelere güvenmekten kaçının. Yönlendirme işlemleri istemciler arasında farklılık gösterir ve imzalı bir isteği yönlendirmek hedef, yöntem ve gövde konusunda belirsizlik yaratabilir. Sağlayıcıyı doğrudan son HTTPS uç noktasıyla yapılandırın.
Takip olayları için güvenilir bir yanıt politikası
Çoğu takip webhook entegrasyonu için aşağıdaki politika makul bir başlangıçtır:
200veya202, olay kimlik doğrulamasından geçip kalıcı olarak depolandıktan veya güvenilir bir kuyruğa yerleştirildikten sonra döndürülmelidir.- Geçersiz imza, geçersiz kimlik doğrulama veya kalıcı olarak kullanılamayan bir yük için sağlayıcının belgelenmiş kurallarını izleyerek 4xx döndürülmelidir.
- Geçici bir hata kalıcı kabulü engellediğinde 5xx döndürülmelidir.
- Güvenli biçimde tanınan yinelenen bir olay için, yinelenen iş etkilerini önleyerek başarılı yanıt döndürülmelidir.
- İşleyici hızlı tutulmalı ve onaylama gecikmesi ölçülmelidir.
- Üretime geçmeden önce zaman aşımı, yeniden deneme, yinelenen, sırası dışında gelen, hatalı biçimli ve sağlayıcı kesintisi senaryoları test edilmelidir.
Bir takip API'si entegre ediyorsanız sağlayıcının webhook belgeleriyle başlayın ve kabul edilen başarı kodlarını, istek imzalama yöntemini, zaman aşımını, yeniden deneme tetikleyicilerini, yük şemasını ve olay tanımlayıcısını doğrulayın. 17TRACK entegrasyonları için resmî Tracking API belgeleri, sağlayıcıya özel sözleşmeyi genel HTTP uygulamalarından çıkarmak yerine doğrulamak için uygun yerdir.
Uygulama kontrol listesi
- Uç noktaya HTTPS üzerinden erişilebiliyor ve sabit bir üretim URL'si var.
- Kimlik doğrulama ve imza doğrulaması işleme başlamadan önce gerçekleşiyor.
- Ham istek veya doğrulanabilir bir temsili, gerektiğinde imza kontrolleri ve sorun giderme için saklanıyor.
- Başarı yanıtı gönderilmeden önce olay kalıcılaştırılıyor.
- Yinelenen teslimatlar güvenli ve geri döndürülemez eylemleri tekrarlamıyor.
- Çalışanlar, gönderenin HTTP yeniden deneme döngüsünden bağımsız olarak dahili işlemeyi yeniden deneyebiliyor.
- Günlükler, sırları açığa çıkarmadan olay kimliğini, teslimat zamanını, yanıt kodunu, işleme durumunu ve ilişkilendirme kimliğini içeriyor.
- Alarmlar uç nokta zaman aşımlarını, 4xx doğrulama hatalarını, 5xx kesintilerini, kuyruk gecikmelerini ve yinelenen teslimatları ayırt ediyor.
- Belgelenmiş sağlayıcı davranışı gerçek veya korumalı alan olaylarıyla test edildi.
SSS
Bir webhook için 200 OK, 202 Accepted'dan daha mı iyidir?
Hiçbiri evrensel olarak daha iyi değildir. İstek kabul edildiğinde ve entegrasyonunuz yanıtı genel bir başarı olarak ele aldığında 200 OK kullanın. Olay asenkron işleme için kabul edildiğinde 202 Accepted kullanın. Gönderenin seçilen 2xx yanıtını başarılı olarak sınıflandırdığını doğrulayın.
Bir webhook uç noktası takip güncellemesi tamamen işlenene kadar beklemeli mi?
Genellikle hayır. Yalnızca olayın kimliği doğrulanana, doğrulanana ve kalıcı olarak kabul edilene kadar beklemelidir. Uzun süren işler normalde onaydan sonra gerçekleşmelidir; böylece yavaş bir bağımlılık önlenebilir bir zaman aşımına ve yeniden denemeye neden olmaz.
Aynı takip olayı iki kez geldiğinde ne olmalıdır?
Sağlayıcının olay kimliğini veya dikkatle tasarlanmış eşdeğer bir anahtarı kullanarak olayı tanıyın, yinelenen yan etkileri atlayın ve olay daha önce kabul edildiyse başarılı yanıt döndürün. Bu, yeni işleme hatalarını gizlemeden yeniden denemeleri güvenli hâle getirir.
Geçersiz imza 400 mü yoksa 401 mi döndürmelidir?
Seçim, kimlik doğrulama modelinize ve sağlayıcının belgelenmiş beklentilerine bağlıdır. Her ikisi de reddi ifade edebilir; ancak tutarlılık, evrensel olarak birini seçmekten daha önemlidir. Özgünlüğünü doğrulayamadığınız bir olayı onaylamayın.
5xx yanıtı her zaman yeniden denemeye neden olur mu?
Hayır. Birçok webhook sistemi zaman aşımlarını ve sunucu hatalarını yeniden dener; ancak yeniden deneme tetikleyicileri ve zamanlamaları sağlayıcıya özeldir. Yeniden denemeleri belgelenmiş bir entegrasyon davranışı olarak ele alın ve bunları bir test ortamında doğrulayın.
Kaynaklar
- RFC 9110: HTTP Semantics — başarılı, istemci hatası, sunucu hatası, yönlendirme ve yanıt işleme tanımları.
- RFC 6585: Additional HTTP Status Codes —
429 Too Many Requestsbelirtimi. - Stripe Webhooks Documentation — webhook yanıtları, asenkron işleme ve yinelenen olayların ele alınması hakkında pratik rehber.
- GitHub Docs: Handling Webhook Deliveries — webhook entegrasyonları için teslimat inceleme ve operasyonel hususlar.
- 17TRACK Tracking API Documentation — takip API entegrasyonlarını uygularken kontrol edilmesi gereken sağlayıcıya özgü belgeler.


