Webhook entegrasyonu: Doğrulama, tekrar teslim ve olay eşleştirme
· PoolByte Technology
Webhook entegrasyonu, bir sistemde oluşan olayın başka uygulamaya HTTP isteğiyle bildirilmesini sağlar. Ödeme sonucu, sipariş güncellemesi veya depo hareketi gibi olaylarda kullanılabilir. Güvenilir bir entegrasyon için isteğin gelmesi yeterli değildir: kaynağın doğrulanması, olayın doğru kayda eşlenmesi ve tekrar bildirimlerinin aynı işlemi çoğaltmaması gerekir.
Tarayıcı dönüşü ile sunucu bildirimini ayırın
Müşteri ödeme ekranından sitenize geri dönebilir veya sekmeyi kapatabilir. Tarayıcının bir başarı adresine gelmesi, ödeme sağlayıcısının güvenilir sunucu bildirimiyle aynı şey değildir. İşlem durumu sağlayıcının belgelenmiş doğrulama yöntemine göre değerlendirilmelidir. Kullanıcı dönüş ekranı ise kişiye mevcut durumu anlaşılır biçimde göstermek için tasarlanır.
Bu ayrım diğer entegrasyonlarda da geçerlidir. Depo panelinin “gönderildi” ekranı ile stok yazılımına ulaşan bildirim farklı aşamalardır. Uygulama her aşamayı ayrı kaydetmeli; kullanıcı arayüzündeki metin, henüz doğrulanmamış işlemi tamamlanmış gibi göstermemelidir. İki sistemin kayıt kimlikleri arasında açık bir eşleşme kurulmalıdır.
Bildirimin kaynağını sağlayıcının yöntemiyle doğrulayın
Her sağlayıcı aynı imza düzenini kullanmaz. İmza başlığı, ham istek gövdesi ve zaman kontrolü gibi ayrıntılar resmî dokümana göre uygulanmalıdır. Örnek bir sistemin algoritmasını başka hizmete kopyalamayın. Erişim anahtarları loglara veya müşteriye açık hata mesajlarına yazılmamalıdır.
GitHub webhook iyi uygulamaları güvenli bağlantı ve doğrulama yaklaşımını açıklar. Stripe webhook dokümanı kendi bildirim imzası ve teslim davranışını belgeler. Bu kaynaklar örnek sağlayıcılardır; kullanılacak ödeme veya sipariş hizmetinin kendi kuralları esas alınmalıdır.
Aynı olayın tekrar gelmesini normal bir senaryo sayın
Bir olay birden fazla kez teslim edilebilir. Alıcı geç yanıt verirse gönderen başarılı kabul etmediği isteği yeniden gönderebilir. Uygulama aynı olay kimliğini veya iş anahtarını tanıyıp daha önce tamamlanan işlemi güvenli biçimde ele almalıdır. Buna idempotent işlem tasarımı denir; tekrar geldiğinde ikinci kez hizmet açmamak buna örnektir.
Olay kaydı ile işin tamamlanması arasında hata oluşabilir. Bu yüzden yalnız “olay daha önce görüldü” kaydı yeterli olmayabilir; işleniyor, tamamlandı veya hata aldı gibi durumların tutarlı yönetimi gerekir. Veritabanı işlemleri, benzersiz kayıt kuralları ve kuyruk tasarımı geliştirici tarafından birlikte ele alınmalıdır. Aynı bildirimin iki eşzamanlı istekle gelmesi de test edilmelidir.
Eşleşmeyi tahmin edilen müşteri bilgisine dayandırmayın
E-posta adresi müşteri iletişimi için kullanılabilir, fakat tek başına güvenilir ödeme eşleştirme anahtarı olarak kabul edilmemelidir. Sipariş kimliği, sağlayıcı işlem kimliği, tutar ve para birimi gibi alanlar entegrasyonun sözleşmesine göre kontrol edilir. Aynı müşteri aynı gün iki sipariş verebilir; aynı tutarlı siparişler de bulunabilir.
İade, kısmi işlem veya sonraki durum değişikliği varsa bunlar ayrı olay türleri olabilir. “Başarılı” kelimesi görülen her bildirimde aynı sipariş durumunu uygulamayın. Uygulamanın kendi durum geçişlerini tanımlayın. İşlenemeyen bir olay sessizce kaybolmak yerine yetkili ekibin inceleyebileceği kontrollü hata kaydına dönüşmelidir.
Teslimi ve işlenmeyi ayrı ölçün
Bildirimi kabul eden uç nokta gereksiz uzun işler yaparsa zaman aşımı yaşanabilir. Bazı mimarilerde olay doğrulanıp güvenilir biçimde kaydedilir, asıl iş kuyrukta yürütülür. Başarı yanıtı göndermenin hangi aşamayı temsil ettiği açık olmalıdır. Sağlayıcının beklediği yanıt kodu ve yanıt süresi kendi dokümanından doğrulanmalıdır.
Kayıtlarda olay kimliği, teslim zamanı, eşleşen yerel kayıt ve iş sonucu bulunabilir. Tüm istek gövdesini düşünmeden saklamak hassas bilgileri gereksiz yere çoğaltabilir. Teşhis için gerekli alanlarla sınırlı kayıt, erişim kontrolü ve saklama süresi planlayın. Gecikme ve başarısız olay sayısını izlemek, müşterinin hata bildirmesini beklemekten daha erken sinyal verebilir.
Yayından önce test edilecek durumlar
- Geçerli ve doğru kayda bağlı örnek olay.
- Geçersiz imza veya eksik zorunlu alan.
- Aynı olayın tekrar ve eşzamanlı teslimi.
- Tutarsız tutar, para birimi veya sipariş kimliği.
- Beklenmeyen sırada gelen olaylar.
- İşleme sırasında kesinti ve kontrollü yeniden deneme.
Test sağlayıcının deneme ortamında veya yetkilendirilmiş test düzeninde yapılmalıdır. Gerçek siparişi elle ödendi işaretlemek, entegrasyonun çalıştığını kanıtlamaz. Eksik olaylar için sağlayıcının desteklediği sorgulama ve uzlaştırma yöntemini ayrıca değerlendirin.
Entegrasyon ihtiyacınızı kullanılan hizmet ve olay türleriyle birlikte PoolByte'a iletebilirsiniz. Periyodik uzlaştırma işlerinde cron otomasyonu rehberine, kontrollü denemeler için staging rehberine bakabilirsiniz.