Webhook ile Gönderi Takibi: Takip Webhook'ları Polling'e Karşı Nasıl Çalışır (Payload'lar, Yeniden Denemeler ve Kurulum)

Gönderi takip webhook'ları, bir takip hizmetinin bildirilecek bir güncellemesi olduğunda uygulamanıza bir HTTP isteği gönderir. Yoklama bunun ters yönde çalışır: uygulamanız en güncel takip bilgilerini tekrar tekrar ister. Gönderi verilerini bir sipariş yönetim sistemine, mağazaya veya müşteri bildirim hizmetine bağlayan geliştiriciler için webhook'lar, desteklendiğinde genellikle birincil güncelleme mekanizması olarak daha iyi bir seçenektir; hedefli yoklama ise kaçırılan güncellemelerin kurtarılmasına ve kayıtların eşleştirilmesine yardımcı olabilir.

Her iki yöntem de taşıyıcının bir paketi daha erken taramasını sağlamaz. İkisi de takip kaynağının yeni bilgileri ne zaman alıp kullanıma sunduğuna bağlıdır. Pratik fark, uygulamanızın bu bilgiyi nasıl öğrendiği, ne kadar istek trafiği oluşturduğu ve teslimat başarısız olduğunda ne olduğu ile ilgilidir.

Takip webhook'ları ile yoklama: operasyonel fark

Bunlar birbirleriyle rekabet eden takip veritabanları değil, entegrasyon modelleridir. Bir taşıyıcı veya takip platformu, farklı erişim koşullarıyla bu modellerden birini ya da her ikisini sunabilir. Tüm webhook hizmetlerinin aynı garantileri sunduğunu varsaymak yerine kullanmayı planladığınız belirli API'nin davranışını karşılaştırın.

Güncellemelerin zamanında alınması önemliyse ve ekibiniz güvenilir bir alıcıyı çalıştırabiliyorsa önce webhook'ları seçin. Gelen uç noktalar pratik değilse, gönderi hacmi düşükse veya kaynak uygun webhook'lar sunmuyorsa önce yoklamayı seçin. Kaçırılan güncellemeler müşteri iletişimini veya operasyonları aksatacaksa ve API eşleştirmeyi destekliyorsa hibrit bir tasarım kullanın.

Webhook'ların daha ucuz olduğunu varsaymayın. Abonelik ücretleri, takip kaydı, API çağrıları, olay teslimatı ve altyapı farklı şekilde ücretlendirilebilir. Daha az isteği daha düşük faturanın kanıtı olarak görmek yerine gerçek ticari koşulları ve beklenen iş yükünü karşılaştırın.

Taşıyıcı taraması ile uygulamanız arasında neler olur?

1. Gönderiyi tanımlayın. Takip numarasını, gerektiğinde taşıyıcı bilgilerini ve dahili gönderi referansını ilişkilendirin. Bazı hizmetler izleme başlamadan önce kayıt gerektirir.
2. Olay teslimatını yapılandırın. Bir HTTPS geri çağırma URL'si sağlayın ve desteklenen olay aboneliklerinden istediklerinizi seçin.
3. Kaynak takip bilgilerini alır. Bir taşıyıcı taraması veya durum değişikliği takip hizmeti tarafından kullanılabilir hale gelir.
4. Hizmet bir webhook gönderir. İstek tam bir takip anlık görüntüsü, tek bir kontrol noktası veya API araması gerektiren yalnızca bir referans içerebilir.
5. Alıcınız doğrular ve saklar. İsteğin kimliğini doğrulayın, yapısını kontrol edin ve olayı kalıcı olarak kaydedin veya kuyruğa alın.
6. Bir çalışan iş sistemlerini günceller. Durumları normalleştirin, gönderi kayıtlarını güncelleyin ve yalnızca hâlâ uygun olan işlemleri tetikleyin.

Bir webhook teslimatı fiziksel teslimatla aynı şey değildir. Bu, gönderi bilgileri hakkında bir mesajdır. Aynı şekilde başarılı bir webhook yanıtı, bir e-postanın gönderildiğini veya bir sipariş kaydının güncellendiğini kanıtlamaz; bunlar kendi izlemelerini gerektiren sonraki işleme sonuçlarıdır.

Takip webhook yükünü okuma

Aşağıdaki JSON, örnek bir entegrasyon tasarımıdır; 17TRACK yükü veya evrensel bir şema değildir. Gerçek alan adları, durum kodları, zaman damgası biçimleri ve olay tanımlayıcıları seçilen sağlayıcının belgelerinden alınmalıdır.

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

Veri modelinizde üç saati birbirinden ayırın: gönderi olayının gerçekleştiği zaman, sağlayıcının mesajı oluşturduğu zaman ve uygulamanızın mesajı aldığı zaman. Gecikmiş bir kontrol noktası daha yeni bir kontrol noktasından sonra ulaşabilir. Ofset içermeyen bir zaman damgası da açıkça yorumlanmalıdır; her taşıyıcı yerel zaman damgasını sessizce UTC olarak kabul etmeyin.

Dahili gönderi referansınızı sağlayıcının tanımlayıcılarıyla birlikte tutun. Özellikle farklı taşıyıcı bağlamlarında yalnızca takip numarası kalıcı bir genel tanımlayıcı olarak yeterli olmayabilir. Bölünmüş siparişlerde bir paketin teslim edildi durumunun tüm siparişi tamamlandı olarak işaretlemesine izin vermek yerine gönderi düzeyinde kayıtlar tutun.

Orijinal durumu ve açıklamayı normalleştirilmiş iş durumunuzun yanında koruyun. Uygulamanız birkaç taşıyıcı mesajını “taşımada” olarak eşleyebilir; ancak destek personelinin bir gecikmeyi anlamak için yine de orijinal kontrol noktasına ihtiyacı olabilir. Tahmini teslimat tarihlerini tahmin olarak değerlendirin ve eksik bir alanı mevcut bir değeri temizlemeye yönelik açık bir talimattan ayırın.

Yeniden denemeler, onaylar ve yinelenen olaylar

Webhook teslimatı zaman aşımı, ağ kesintileri, kimlik doğrulama hataları veya kullanılamayan bir alıcı nedeniyle başarısız olabilir. Bir sağlayıcı yeniden deneme yapabilir; ancak evrensel bir yeniden deneme takvimi, saklama süresi veya azami deneme sayısı yoktur. Hangi yanıtların başka bir denemeyi tetiklediğini, yönlendirmelerin nasıl ele alındığını ve manuel yeniden teslimin mevcut olup olmadığını doğrulayın.

Kalıcı kabulden sonra onaylayın

İstek yolunu kısa tutun: isteği doğrulayın, kabul edilen işi kalıcı olarak kaydedin ve sağlayıcının gerektirdiği başarı yanıtını döndürün. E-postaları gönderin ve daha yavaş iş operasyonlarını eşzamansız olarak gerçekleştirin. HTTP belirtimi 202 Accepted durumunu tamamlanmış işleme değil, işlenmek üzere kabule karşılık gelecek şekilde tanımlar; ancak sağlayıcınız farklı bir başarı yanıtı gerektirebilir. Sağlayıcının webhook sözleşmesine uyun.

Herhangi bir şeyi kaydetmeden önce başarı döndürmek, işleminiz çökerse güncellemenin kaybolmasına neden olabilir. Her sonraki işlemin tamamlanmasını beklemek ise zaman aşımı ve başka bir teslimat denemesi riskini artırır. Kalıcı bir gelen kutusu veya kuyruk, alma ile işleme arasında bir sınır sağlar.

İşlemeyi idempotent hâle getirin

İdempotency, aynı olayın tekrar işlenmesinin iş etkilerini tekrarlamaması anlamına gelir. Sunucunuz bir olayı kabul ettikten sonra onayı kaybolursa gönderen yeniden deneyebilir. Bu nedenle yinelenen teslimat rutin bir test senaryosu olmalıdır.

• Mevcut olduğunda belgelenmiş bir olay tanımlayıcısını, doğru sağlayıcı veya hesap kapsamında, yinelenenleri ayırt etme anahtarı olarak kullanın.
• Tanımlayıcı yoksa kararlı olay alanlarından bileşik bir anahtar tasarlayın ve çakışma risklerini test edin.
• Depolamada benzersizliği atomik olarak zorunlu kılın; ayrı bir “kontrol et, sonra ekle” sırası eşzamanlı teslimat sırasında yarış durumuna neden olabilir.
• Sonraki işlemleri de koruyun. Yinelenen bir olay başka bir teslimat bildirimi göndermemeli veya finansal bir işlemi tekrarlamamalıdır.
• Saklama süresini sağlayıcının yeniden oynatma davranışına ve kurtarma gereksinimlerinize göre belirleyin; yinelenen kayıtlarını hemen silmeyin.

Kronolojik varışı varsaymayın

Bir istek en son geldi diye mevcut gönderi durumunun üzerine yazmayın. Olayın anlamını, zaman damgalarını ve belgelenmiş sıra bilgilerini karşılaştırın. Geç gelen kontrol noktalarını geçmişte koruyun, ancak görüntülenen durumu otomatik olarak geriye taşımayın. Bununla birlikte belgelenmiş düzeltmelere izin verin: teslim edilen gönderilerin asla değişemeyeceğine ilişkin katı bir kural, meşru istisnaları veya düzeltilmiş bilgileri gizleyebilir.

Pratik kurulum kontrol listesi

1. Sağlayıcı sözleşmesini doğrulayın

Uygulamadan önce kayıt gereksinimlerini, desteklenen olayları, yük biçimini, kimlik doğrulamayı, yanıt beklentilerini, zaman aşımını, yeniden deneme davranışını ve API sınırlarını doğrulayın. Bir bildirimin anlık görüntüyü mü yoksa artımlı bir değişikliği mi temsil ettiğini, teslimatların birden fazla kayıt içerip içermediğini ve abone olmanın başlangıç durumunu gönderip göndermediğini kontrol edin.

Bir 17TRACK entegrasyonu için resmi Tracking API page ve API documentation ile başlayın. İstek alanlarını ve geri çağırma gereksinimlerini belirlemek için sağlayıcıya özgü belgeleri kullanın; yukarıdaki genel yük bunun yerine geçmez. Kullanmayı planladığınız entegrasyon için erişim koşullarını ve operasyonel sınırları doğrulayın.

2. Alıcı uç noktayı güvenli hâle getirin

HTTPS ve sağlayıcının belgelediği kimlik doğrulama mekanizmasını kullanın. HMAC imzası kullanıyorsa tam olarak belirttiği imzalı girdiyi doğrulayın. Ham istek baytları imzalanıyorsa doğrulamadan önce JSON'u ayrıştırmak ve yeniden serileştirmek bu baytları değiştirebilir ve imzayı geçersiz kılabilir. Gizli anahtardan türetilen imza değerlerini sabit zamanlı karşılaştırmayla karşılaştırın.

İmzalı zaman damgaları veya teslimat tanımlayıcıları mevcutsa belgelenmiş yeniden oynatma kontrollerini uygulayın. Geçerli bir imza bir mesajın kimliğini doğrular, ancak tek başına mesajın güncel olduğunu göstermez. Gizli bilgileri URL'lerden ve uygulama günlüklerinden uzak tutun, gizli anahtar döndürmeyi destekleyin ve istek boyutlarını sınırlayın. IP izin listesi, bakımı yapılan adres aralıkları mevcut olduğunda ek bir kontrol olabilir; ancak mesaj kimlik doğrulamasının yerini tutmaz.

3. Almayı iş sürecinden ayırın

Kabul edilen bir olayı izlemek ve güvenli biçimde yeniden oynatmak için yeterli bilgiyi saklayın. Kuyruk çalışanları güncellemeyi normalleştirmeli, durum geçişi kurallarını uygulamalı ve işlem sonuçlarını kaydetmelidir. Tekrar tekrar başarısız olan işleri sonsuza kadar yeniden denemek yerine incelenebilir bir ölü mektup iş akışına taşıyın. Takip yükleri müşteriyle ilgili bilgiler içerebileceğinden erişimi ve saklama süresini sınırlayın.

4. Başlatmadan önce hata yollarını test edin

• Aynı olayı eşzamanlı teslimatlar da dâhil olmak üzere iki kez gönderin.
• Daha yeni bir kontrol noktasından sonra daha eski bir kontrol noktası teslim edin.
• Bir kuyruk kesintisini ve alım sonrasında çalışan çökmesini simüle edin.
• Geçersiz kimlik doğrulamayı, hatalı JSON'u ve aşırı büyük istekleri test edin.
• Bilinmeyen gönderileri, eksik isteğe bağlı alanları ve eklenen alanları test edin.
• Teslim edilen bir paketin bölünmüş siparişi tamamlamadığını doğrulayın.
• Kurtarma sonrasında bir olayı yeniden oynatın ve bildirimlerin yinelenmediğini doğrulayın.

Güvenli olduğunda eklenen alanlara karşı toleranslı olun; ancak bilinmeyen durum değerlerini sessizce yeniden yorumlamayın. Ham değeri koruyun ve tanınmayan durumları tanımlanmış bir geri dönüş veya inceleme sürecine yönlendirin.

Yoklamanın hâlâ yararlı olduğu yerler

Yoklama ilk senkronizasyon, bir kesinti sonrası kurtarma ve beklenen güncellemeleri ulaşmamış gönderilerin kontrol edilmesi için yararlıdır. Ancak tek başına sessizlik webhook arızasının kanıtı değildir: bir pakette gerçekten yeni tarama olmayabilir. Sessiz olan her gönderinin uyarı gerektirdiğini varsaymak yerine API'nin mevcut durumuyla veya geçmişiyle eşleştirme yapın.

Ölçek planlaması için basitleştirilmiş yoklama modeli, istek başına bir gönderi varsayımıyla saatlik istek sayısı ≈ etkin gönderiler × gönderi başına saatlik yoklama sayısı şeklindedir. Toplu uç noktalar bu hesabı değiştirir. Örnek olarak saatte dört kez kontrol edilen 1.000 gönderi, yeniden denemelerden önce saatte 4.000 istek oluşturur; bu bir aritmetik hesabıdır, sağlayıcı kotası veya fiyat tahmini değildir.

Kontrolleri gönderi etkinliğine ve iş riskine göre planlayın, hız sınırlarına uyun ve işlerin aynı anda başlamaması için rastgele sapma ekleyin. Yeniden denenebilir hatalar için sınırlı geri çekilme kullanın ve geçerli sunucu yönlendirmelerine uyun. Kalıcı kimlik bilgisi veya doğrulama hatalarını düzeltmeden tekrar tekrar yeniden denemeyin.

Pratik bir hibrit sistem, rutin güncellemeler için webhook'ları ve şüpheli boşluklar için hedefli API okumalarını kullanır. Alım hatalarını, kuyruk yaşını, işleme hatalarını, yinelenme oranlarını ve eşleştirme uyumsuzluklarını ayrı ayrı izleyin. Zaman damgaları güvenilir olduğunda kaynak verisi gecikmesini webhook teslimat gecikmesinden ve dahili işleme gecikmesinden ayırın.

SSS

Takip webhook'ları gerçek zamanlı mıdır?

Bir sonraki yoklama döngüsünü beklemekten kaynaklanan gecikmeyi azaltabilirler. Anında taşıyıcı taramalarını veya anlık kaynak güncellemelerini garanti etmezler. Uçtan uca güncellik; taşıyıcının bildirimini, sağlayıcının işlemesini, isteğin teslim edilmesini ve kendi uygulamanızı kapsar.

Webhook'ları etkinleştirdikten sonra yoklamayı tamamen durdurabilir miyim?

Sağlayıcının kurtarma özellikleri ve iş gereksinimleriniz bunu kabul edilebilir kılıyorsa mümkün olabilir. Operasyon açısından önemli gönderi kayıtları için bir eşleştirme yöntemi bulundurun. Bu yöntem, her gönderinin sürekli yoklanması yerine hedefli olabilir.

Webhook uç noktam çevrimdışı olursa ne olur?

Kurtarma, gönderenin belgelenmiş yeniden deneme politikasına bağlıdır. Yeniden denemelerin sonsuza kadar devam ettiğini varsaymayın. Uç noktayı geri yükledikten sonra başarısız teslimatları inceleyin, desteklenen yeniden teslim araçlarını kullanın ve mümkün olduğunda etkilenen gönderileri API üzerinden eşleştirin.

Her webhook müşteri bildirimi tetiklemeli mi?

Hayır. Bir olay yinelenen, geçmişe ait bir kontrol noktası veya müşteriye gösterilen durumu değiştirmeyen bir güncelleme olabilir. Bildirimleri, istisnalar ve düzeltmeler için kurallarla birlikte yinelenenleri ayıklanmış iş geçişlerinden tetikleyin.

Başarılı bir HTTP yanıtı, gönderi güncellemesinin tamamlandığı anlamına mı gelir?

Gerekmez. Eşzamansız bir tasarımda bu, alıcının olayı üzerinde anlaşılmış sözleşme kapsamında kabul ettiği anlamına gelir. Kabul edilen bir isteğin başarısız bir iş akışını gizlememesi için işleme tamamlanmasını ve sonraki bildirim sonuçlarını ayrı ayrı izleyin.

Kaynaklar

• RFC 9110: HTTP Semantics — işlenmek üzere kabul ve Retry-After dâhil HTTP yanıt semantiği.
• RFC 2104: HMAC—Keyed-Hashing for Message Authentication — imza doğrulama kılavuzunda başvurulan HMAC yapısı.
• GitHub Docs: Best practices for using webhooks — HTTPS, gizli bilgiler, eşzamansız işleme ve teslimat tanımlama hakkında genel mühendislik kılavuzu; hizmete özgü kuralları gönderi sağlayıcısı davranışını belirlemez.
• 17TRACK Tracking API — bir 17TRACK takip entegrasyonunu değerlendirmek için resmi giriş noktası.
• 17TRACK API documentation — uygulama gereksinimleri için sağlayıcıya özgü başvuru kaynağı.