Webhook, başka bir sistemden gelen bir bildirimdir. Bu bildirimi, “bildirimi al, kaydı güncelle ve başarı mesajı gönder” şeklinde kusursuzca sıralanmış bir talimat olarak ele almak cazip gelebilir. Ancak gerçek entegrasyonlar, daha özenli bir sözleşme 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ı baştan dikkate alarak tasarı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. Bunun ardından 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ı kapladığında, 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 kaydedilmeden önce başarı onayı 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ı kapsamında kaydederim. Bu sayede, eşzamanlı olarak gerçekleşen yinelenen teslimatlar tek bir kayıtlı makbuzda birleştirilir.
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ı sonradan gelen eyleme yol açabilir. İş eyleminin kendine özgü bir kimliğe ve geçiş kurallarına ihtiyacı vardır.
Stripe’ın webhook belgeleri, yinelenen teslimatları açıkça açıklamaktadır ve teslimat sırasını garanti etmemektedir. Geliştirme oturumunda gözlemlenen zamanlamayı bir sözleşme olarak kabul etmek yerine, bu belgelenmiş davranışları alıcı tasarımında 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ını paylaşıyorsa veya farklı sistemler farklı saatler kullanıyorsa, sadece zaman damgası sıralamayı belirlemek için yetersiz kalabilir.
Karar, verilerin kullanım amacına bağlıdır. Yerel bir durum rozeti için yalnızca güncel durum bilgisi yeterli olabilir. Bir defter veya denetim geçmişi için ise değişikliklerin gerçek sırası ve anlamı gereklidir. 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 için sınırlı bir yeniden deneme politikası belirlenmelidir. İşlem ilerleyemediğinde, bir inceleme kuyruğu veya ölü mesaj kuyruğu, olay referansını ve hata nedenini saklamalıdır. Yeniden oynatma işlemi sırasında, orijinal denemede uygulanan tekilleştirme ve yetkilendirme kuralları kullanılmalıdır.
Yararlı ölçütler arasında, işlenmemiş en eski olayın yaşı, işleme gecikmesi, tekrarlanan hatalar ve mutabakat uyuşmazlıkları yer alır. Bu ölçütler, toplam webhook isteği sayısından daha net bir şekilde müşterinin yaşadığı gerçek gecikmeyi ortaya koyar.
Ağın neler yapabildiğ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 kolay hale getirir.
25 Eylül 2026 tarihinde güncellenmiştir.