Idempotency ve Callback Güvenliği: Entegrasyonun İki Kritik Kararı
Idempotency nedir?
Idempotency, aynı isteğin bir kez ya da defalarca gönderilmesinin sonucu değiştirmemesidir. Ağ zaman aşımı yaşandığında istemci isteği tekrarlar; sunucu bu tekrarı yeni bir işlem sanarsa ikinci sipariş, ikinci fatura veya ikinci ödeme oluşur. Bu nedenle yeni kayıt üreten her uçta tekrarın nasıl ele alınacağı tanımlanmalıdır.
Uygulamada idempotency nasıl kurulur?
- İstemci her işlem için benzersiz bir işlem anahtarı üretir ve isteğe ekler. Anahtar, kullanıcı yeniden denediğinde de aynı kalmalıdır.
- Sunucu anahtarı ve isteğe ait sonucu saklar.
- Aynı anahtarla ikinci istek geldiğinde yeni kayıt açılmaz; ilk işlemin sonucu aynı yanıtla döndürülür.
- Anahtarların saklanma süresi tanımlanır (ör. işlem tipine göre belirli bir gün sayısı).
Dikkat edilecek nokta: anahtar aynı ama gövde farklıysa bu bir hatadır ve açık bir hata koduyla reddedilmelidir; sessizce ilk sonucu döndürmek gerçek bir uyuşmazlığı gizler.
HTTP tarafında `GET`, `PUT` ve `DELETE` yöntemleri tanım gereği idempotent kabul edilir; `POST` değildir. Bu yüzden işlem anahtarı esas olarak `POST` uçlarında gerekir.
Callback (webhook) güvenliği
Dışarıdan gelen bildirim çağrıları, sisteminizde durum değiştirdiği için saldırı yüzeyidir. Beş temel önlem:
- İmza doğrulama: gönderici, gövdenin paylaşılan bir gizli anahtarla üretilmiş imzasını başlıkta iletmeli; siz aynı hesabı yapıp karşılaştırmalısınız.
- Zaman damgası ve tekrar koruması: eski imzaların yeniden oynatılmasını engellemek için dar bir zaman penceresi uygulayın ve görülen imzaları kısa süre saklayın.
- Gövdenin ham hâliyle doğrulanması: imza, JSON yeniden serileştirilmeden önceki ham gövde üzerinden hesaplanmalıdır.
- Bildirimi kaynak olarak kabul etmeyin: bildirim yalnızca "bir şey oldu" bilgisidir. Tutar, durum ve sonuç, göndericinin API'sinden yeniden okunarak doğrulanmalıdır.
- Alma ile işlemeyi ayırın: çağrıyı hızla kabul edip kuyruğa yazın, iş mantığını kuyruktan yürütün. Böylece gönderici tarafında zaman aşımı ve gereksiz tekrar oluşmaz.
"Tam olarak bir kez" bir yanılgıdır
Dağıtık sistemlerde mesajın tam olarak bir kez ulaştığı garanti edilemez. Gerçekçi hedef, mesajın en az bir kez ulaşması ve alıcının tekrarları etkisiz hâle getirmesidir. Bu yüzden tüketici tarafında da işlem anahtarı veya olay kimliği ile tekrar kontrolü yapılmalıdır.
Hata ve yeniden deneme politikası
- Geçici hatalarda (ağ, 5xx, hız sınırı) artan bekleme süreleriyle yeniden deneyin ve bekleme süresine rastgele bir sapma ekleyin.
- Kalıcı hatalarda (doğrulama hatası, yetkisiz) tekrar denemeyin; kaydı hatalı kuyruğa alın.
- Her yeniden denemenin kaydını tutun; hangi isteğin kaç kez denendiği görünmeden mutabakat yapılamaz.
Ölçülmesi gereken değerler
Entegrasyon sağlığı üç sayıyla izlenir: bekleyen kuyruk uzunluğu, ortalama işlenme gecikmesi ve hatalı kuyruğa düşen kayıt sayısı. Bu ölçümlerin finansal mutabakattaki karşılığını [banka entegrasyonu rehberinde](/blog/banka-entegrasyonu-rehberi) bulabilirsiniz. Bu üçü panoda yoksa entegrasyon "çalışıyor" varsayımına dayanır.
Sık sorulan sorular
İşlem anahtarını sunucu üretebilir mi?
Üretebilir, ancak asıl fayda anahtarın istemcide üretilmesindedir. Sunucu üretirse, yanıtın kaybolduğu senaryoda istemci anahtarı öğrenemez ve tekrar denemesi yeni bir işlem olur.
Webhook yerine düzenli sorgulama (polling) kullanmak doğru mu?
Hacim düşükse ve gecikme toleransı varsa polling daha basit ve daha güvenilirdir. Yüksek hacimde polling gereksiz yük üretir; bu durumda webhook ile polling'i birlikte kullanmak yaygındır: webhook hızlı bildirim, periyodik sorgulama ise kaçan olayların telafisi için.
Entegrasyon testinde en sık atlanan senaryo hangisidir?
Yanıtın kaybolduğu senaryodur. İstek başarıyla işlendi ama istemciye yanıt ulaşmadı durumu, gerçek hayatta sık görülür ve tekrar üretilmeden idempotency doğrulanmış sayılmaz.