Webhook bildirimlerinde aynı ödemenin, siparişin veya olayın birden fazla kez işlenmesini önlemek için kimlik, idempotency, kuyruk ve tekrar deneme tasarımı.
Webhook gönderen servis aynı olayı yeniden iletebilir. Alıcı sistemin görevi tekrar gelmeyeceğini varsaymak değil, aynı olayı ikinci kez yan etki üretmeden tanımaktır.
Ödeme, kargo, sipariş veya üyelik servisleri bir durum değişikliğini webhook ile bildirebilir. Ağ kesintisi, zaman aşımı ya da alıcıdan başarı cevabı alınamaması durumunda bildirim tekrar gönderilir. İşlem kodu buna hazır değilse aynı sipariş iki kez açılabilir, stok iki kez düşebilir veya müşteriye birden fazla bildirim gidebilir.
Güvenilir entegrasyon, tek seferlik teslim garantisine dayanmaz. Mesajın kaynağını doğrular, olayı kalıcı olarak kaydeder ve iş kurallarını tekrar çalışsa bile aynı sonucu üretecek biçimde tasarlar.
Her webhook olayı için sağlayıcının benzersiz olay kimliğini saklayın. Aynı kimlik yeniden geldiğinde daha önceki sonucu döndürün; stok, ödeme veya kayıt oluşturma işlemini ikinci kez çalıştırmayın.
İlk adım: isteğin gerçek kaynaktan geldiğini doğrulayın
Bir webhook adresinin gizli olması güvenlik sağlamaz. Sağlayıcı imza mekanizması sunuyorsa ham istek gövdesi, zaman bilgisi ve paylaşılan anahtar üzerinden doğrulama yapılmalıdır. Doğrulama, JSON ayrıştırılmadan veya veri değiştirilmeden önce gerçekleşmelidir.
Zaman damgası kontrolü, daha önce yakalanmış geçerli isteğin uzun süre sonra yeniden gönderilmesi riskini azaltabilir. Kullanılan yöntem sağlayıcının gerçek dokümantasyonuna göre uygulanmalı; tahmini başlık veya imza biçimi üretilmemelidir.
Olay kaydı ile iş sonucunu ayırın
Gelen bildirim önce olay günlüğüne benzersiz kimliğiyle yazılabilir. Kayıt ekleme işlemi benzersiz veritabanı kısıtıyla korunursa aynı olay eşzamanlı iki istekle gelse bile yalnızca biri yeni kabul edilir. Sonrasında olay, kuyruk veya kontrollü görev üzerinden işlenir.
- Sağlayıcı adı ve olay kimliği.
- Olay türü ve ilişkili sipariş/ödeme kimliği.
- Alınma, işlenme ve son deneme zamanı.
- İşlem durumu ve hassas veri içermeyen hata özeti.
- İşleme sonucu oluşan yerel kayıt kimliği.
Idempotent iş kuralı nasıl kurulur?
Idempotent işlem, aynı komut tekrarlandığında yeni bir yan etki üretmez. Ödeme bildirimi için “her bildirimde tahsilat ekle” yerine “bu sağlayıcı işlem kimliğine ait tahsilat yoksa ekle, varsa mevcut sonucu doğrula” yaklaşımı kullanılır.
Durum geçişleri de kontrol edilmelidir. Tamamlanmış siparişi daha eski bir “hazırlanıyor” olayına döndürmemek için olay sırası, sürüm numarası veya sağlayıcının durum zamanı değerlendirilebilir. Bütün webhooklar aynı sırada ulaşmayabilir.
Hızlı cevap, kontrollü arka plan işlemi
Webhook isteği içinde uzun rapor, e-posta veya uzak API çağrıları çalıştırılırsa sağlayıcı zaman aşımına düşüp aynı olayı tekrar gönderebilir. İmza ve temel biçim doğrulandıktan sonra olay kalıcı kuyruğa alınarak hızlı başarı cevabı verilebilir. Asıl işlem arka planda izlenebilir denemelerle yürür.
Tekrar deneme sınırsız olmamalıdır. Geçici ağ hatası ile geçersiz veri ayrılmalı; başarısız olaylar inceleme kuyruğuna taşınmalıdır. Her denemede stok veya bakiye gibi yan etkilerin yeniden oluşmadığı doğrulanmalıdır.
Test edilmesi gereken hata senaryoları
- Aynı olay kimliğini art arda ve eşzamanlı gönderin.
- İmzası hatalı veya zamanı geçersiz isteği deneyin.
- Veritabanı yazımı sonrasında dış servis çağrısını başarısız bırakın.
- Olayları beklenen sıranın tersinde gönderin.
- Kuyruk çalışanını işlem ortasında durdurup yeniden başlatın.
- Başarıyla işlenen olayı manuel tekrar kuyruğuna alın.
Bu kontroller, web tabanlı uygulama ve entegrasyon projelerinde ödeme ya da sipariş gibi geri dönüşü zor işlemler devreye alınmadan önce yapılmalıdır.
Bu rehberden ne öğreneceksiniz?
- Dijital yatırım kararını somut ölçütlerle vermek isteyen işletme sahipleri
- Teknik kapsamı sade bir dille anlamak isteyen proje yöneticileri
- Teklifleri ve çözüm seçeneklerini karşılaştıran ekipler
Karar verirken kontrol edin
- İş hedefi ve beklenen sonucun açık tanımı
- Kullanıcı, veri ve entegrasyon gereksinimleri
- Güvenlik, performans ve bakım sorumlulukları
- Başarıyı gösterecek ölçülebilir kriterler