Webhook, başka bir sistemden gelen bir bildirimdir. Bu bildirimi, “bildirimi al, kaydı güncelle ve başarı mesajı gönder” şeklinde kusursuz bir talimat olarak ele almak cazip gelebilir. Ancak gerçek entegrasyonlar, daha özenli bir anlaşma gerektirir.
Aynı olay birden fazla kez gelebilir. Daha geç gerçekleşen bir olay önce gelebilir. Alıcı işini tamamlamış olsa bile, gönderen yanıtı hiç almadığı için yeniden deneme yapabilir. Ben bu koşulları göz önünde bulundurarak en başından itibaren tasarımımı yapıyorum.
Alıcı sınırını küçük tutun
Alıcı, teslimatı doğrulamalı, temel yapısını kontrol etmeli, kalıcı olarak kaydetmeli ve sağlayıcının protokolüne uygun olarak teslimatı teyit etmelidir. Daha sonra maliyetli iş süreçleri devreye girebilir.
İmza doğrulamasında, sağlayıcı tarafından istenen temsil biçimi kullanılmalıdır. İmza, orijinal istek baytlarını kapsıyorsa, JSON’un önce ayrıştırılması ve yeniden serileştirilmesi, doğrulanacak içeriği değiştirebilir. Doğrulama hataları hiçbir şekilde normal işleme sürecine aktarılmamalıdır.
Dayanıklılık da aynı derecede önemlidir. Olayın kaydedilmesinden önce başarı bildirimi gönderilmesi, işlemin çökebileceği ve gönderenin kabul edildiğini sandığı verilerin kaybolabileceği bir zaman aralığı yaratır. Bellek içi kuyruk bu zaman aralığını ortadan kaldırmaz.
Makbuzları ve iş işlemlerini tekilleştirin
Sağlayıcıyı, bağlı hesabı ve olay tanımlayıcısını bir veritabanı benzersizlik kısıtlaması altında kaydediyorum. Bu sayede, eşzamanlı olarak gerçekleşen mükerrer teslimatlar tek bir saklanan makbuzda birleştirilebiliyor.
Ancak, bir olay kimliği her zaman bir iş işlemi kimliğiyle aynı değildir. İki farklı olay, aynı kaynağı meşru bir şekilde tanımlayabilir veya aynı sonraki eylemi tetikleyebilir. İş eyleminin kendine özgü bir kimliği ve geçiş kuralları olması gerekir.
Stripe’ın webhook belgeleri Yinelenen teslimatları açıkça tanımlar ve teslimat sırasını garanti etmez. Geliştirme oturumunda gözlemlenen zamanlamanın bir sözleşme olduğunu varsaymak yerine, alıcı tasarımında bu belgelenmiş davranışları temel alıyorum.
Geliş sırası yerine durum geçişlerini modelleyin
Bir abonelik entegrasyonunu göz önünde bulundurun. Gecikmeli bir bildirim, daha güncel bir durumu körü körüne üzerine yazmamalıdır. Bazen doğru çözüm, geçerli ve güncel kaynağı almak ve yerel görünümü bununla uyumlu hale getirmektir.
Geçmişteki geçişleri gerektiren işlemlerde, olayı korur ve alana özgü kuralları uygularım. Özellikle birkaç değişiklik aynı zaman damgasına sahip olduğunda veya farklı sistemler farklı saatler kullandığında, sıralamayı belirlemek için sadece bir zaman damgası yeterli olmayabilir.
Karar, verilerin kullanım amacına bağlıdır. Yerel bir durum rozeti için yalnızca güncel durum yeterli olabilir. Bir defter veya denetim geçmişi ise değişikliklerin gerçek sırasını ve anlamını gerektirir. Tek bir genel “son yazma geçerli” işleyicisi, her iki amacı da güvenli bir şekilde karşılayamaz.
İşleme hatalarını görünür hale getirin
Alım durumunu işleme durumundan ayrı tutuyorum. Kabul edilmiş bir olay yine de beklemede, yeniden deneme aşamasında, tamamlanmış veya inceleme bekliyor durumda olabilir. Bu ayrım, sağlıklı bir HTTP yanıt oranının bozuk bir entegrasyonu gizlemesini önler.
Her işleme denemesi, sınırlı bir yeniden deneme politikasına sahip olmalıdır. İşlem ilerleyemediğinde, bir inceleme kuyruğu veya ölü mesaj kuyruğu, olay referansını ve hata nedenini saklamalıdır. Olayın yeniden oynatılması sırasında, orijinal denemede kullanılan tekilleştirme ve yetkilendirme kuralları uygulanmalıdır.
Yararlı ölçümler arasında, işlenmemiş en eski olayın yaşı, işleme gecikmesi, tekrarlanan hatalar ve mutabakat uyuşmazlıkları sayılabilir. Bu ölçümler, toplam webhook isteği sayısından daha net bir şekilde müşterinin gerçek gecikmesini ortaya koyar.
Ağın neler yapabileceğini test edin
Test dizilim, yinelenen teslimat, tersine çevrilmiş varış sırası, kalıcı alım işleminden sonra meydana gelen bir çökme ve harici bir yan etkiden sonra zaman aşımı durumlarını içermektedir. Ayrıca, geçersiz bir imzanın bekleyen bir iş işlemi bile oluşturamayacağını da kontrol ediyorum.
İyi tasarlanmış bir webhook alıcısı, ekibe iki yararlı bilgi sağlar: bildirimin güvenli bir şekilde kabul edilip edilmediği ve hedeflenen iş etkisinin gerçekleştirilip gerçekleştirilmediği. Bu iki bilgiyi birbirinden ayrı tutmak, entegrasyonun işleyişini çok daha kolaylaştırır.
25 Eylül 2026 tarihinde güncellenmiştir.