Problemi ve İşlem Sözleşmesini Tanımlayın

Webhook, ödeme bildirimi, e-posta gönderimi ve üçüncü taraf API çağrıları; ağ kesintisi, zaman aşımı veya sağlayıcının yeniden gönderimi nedeniyle aynı olayın birden fazla kez işlenebileceği akışlardır. Bunun sonucu iki kez sipariş oluşturulması, yinelenen e-posta gönderimi veya aynı ücretlendirme işleminin tekrarlanması olabilir.

Her akış için aşağıdaki kararları yazılı bir sözleşmeye dönüştürün:

• Aynı olay tekrar gelirse beklenen sonuç nedir?
• İşlem tamamen, kısmen veya hiç tekrar edilebilir mi?
• Benzersiz anahtar sağlayıcının olay kimliği mi, yoksa güvenilir biçimde üretilen bir anahtar mı olacak?
• Geçici ve kalıcı hatalar nasıl ayrılacak?
• Kaç yeniden denemeden sonra manuel inceleme gerekecek?
• Kullanıcıya ve üçüncü taraf servise hangi durumda hata bildirilecek?

Bu kararları yalnızca kodun içine dağıtmak yerine API sözleşmesine, teknik dokümana ve teslim kapsamına eklemek bakım maliyetini azaltır. Özellikle freelance projelerde idempotency, retry, gözlemlenebilirlik ve manuel müdahale sorumluluklarının kime ait olduğu açıkça belirtilmelidir.

Idempotent İşleme ve Kalıcı Durum

Idempotency, aynı isteğin bir veya birden fazla kez işlenmesinin gözlenen sonucu değiştirmemesidir. Sağlayıcının olay kimliği veya güvenilir bir idempotency anahtarı kalıcı olarak saklanmalı; işleyici aynı anahtarı gördüğünde daha önce tamamlanan işlemin sonucunu döndürmelidir.

Bu kayıt yalnızca uygulama belleğinde tutulmamalıdır. Birden fazla sunucu, yeniden başlatma veya yatay ölçekleme durumunda ortak veri katmanı gerekir. Eşzamanlı iki isteğin aynı kontrolü geçmesini önlemek için benzersiz kısıt, atomik ekleme ya da veritabanının uygun transaction özellikleri kullanılabilir. Dağıtık kilit tercih ediliyorsa kilidin süresi, yenilenmesi ve istemci çöktüğünde temizlenmesi ayrıca tasarlanmalıdır.

Önerilen akış:

• İsteğin kimlik doğrulamasını ve imzasını, gövde işlenmeden önce doğrula.
• Olay kimliğini atomik biçimde kontrol et; daha önce tamamlandıysa kaydedilmiş sonucu döndür.
• Yeni olay için pending durumunda bir işlem kaydı oluştur.
• Asıl yan etkiyi kontrollü biçimde yürüt ve sonucu transaction kapsamına uygun şekilde kaydet.
• Hata oluştuğunda retryable ve permanent ayrımı yap; durum geçişlerini logla.

Webhook gövdesi, imza doğrulanmadan güvenilir veri kabul edilmemelidir. İmza algoritması, zaman damgası toleransı, tekrar gönderim davranışı ve anahtar rotasyonu dokümante edilmeli; gizli anahtarlar kaynak koda veya loglara yazılmamalıdır.

Kuyruk, Retry ve Hata Yönetimi

Ağır veya dış servislere bağlı işleri webhook isteği içinde tamamlamak yerine doğrulanan olayı bir kuyruğa bırakmak daha güvenlidir. Endpoint hızlı bir onay döner, arka plan tüketicisi işi kontrollü biçimde yürütür. Böylece sağlayıcının zaman aşımı nedeniyle aynı olayı yeniden göndermesi azalır.

Retry körlemesine uygulanmamalıdır. Ağ hataları, timeout ve uygun 5xx yanıtları yeniden denenebilirken geçersiz veri, hatalı kimlik bilgisi veya kalıcı yetki reddi doğrudan inceleme kuyruğuna alınmalıdır. Exponential backoff, jitter ve maksimum deneme sayısı kullanın; rate limit yanıtlarında sağlayıcının verdiği bekleme süresine uyun. Sürekli başarısız işler için dead-letter akışı ve alarm tanımlayın.

Aşağıdaki bilgiler her iş için gözlemlenebilir olmalıdır:

• Olay kimliği, idempotency anahtarı ve korelasyon kimliği
• Mevcut durum, deneme sayısı ve son deneme zamanı
• Son hata nedeni, HTTP durumu ve bağlı servis
• İşlem süresi, kuyrukta bekleme süresi ve sonuç özeti
• Manuel yeniden çalıştırma gerekip gerekmediği

Manuel yeniden çalıştırma da idempotent olmalıdır. Operatör aynı komuta iki kez bastığında yeni bir yan etki oluşmamalı; işlem yetkisi, audit kaydı ve yeniden çalıştırma gerekçesi saklanmalıdır.

Test, Sürümleme ve Geriye Uyumluluk

Mutlu senaryo tek başına yeterli değildir. Birim testleri idempotency anahtarının yorumlanmasını, tamamlanmış işin tekrar yürütülmemesini ve kalıcı hataların retry edilmemesini doğrulamalıdır. Entegrasyon ve yük testleri ise gerçek kuyruğa, veri katmanına ve dış servis timeout davranışına yakın koşulları kapsamalıdır.

En az şu senaryolar otomatik test edilmelidir:

• Aynı olayın art arda iki kez alınması
• Aynı olayın iki tüketici tarafından eşzamanlı işlenmesi
• Veritabanı kaydından sonra dış servisin başarısız olması
• Tüketicinin işlem sırasında kapanması
• Geçersiz imza, bozuk gövde ve eksik alanlar
• İşlenmiş olayın yeni uygulama sürümünde tekrar alınması

Webhook sözleşmesi veya veri şeması değişirken eski olayların nasıl işleneceği belirlenmelidir. Migration işlemlerini geriye uyumlu tasarlayın, sürümleri küçük bir trafik grubunda doğrulayın ve rollback planını önceden test edin. Yeni kodun eski olayları okuyamaması, idempotency kayıtlarının silinmesi veya durum geçişlerinin değişmesi özellikle risklidir.

Teslim Öncesi Teknik Kontrol Listesi

• İmza doğrulama, yetkilendirme, timeout ve gizli anahtar yönetimi gözden geçirildi mi?
• Tekrarlanan olaylarda mükerrer yan etki oluşmadığı kanıtlandı mı?
• Retry, rate limit, dead-letter ve alarm akışları tanımlı mı?
• Loglarda kişisel veya gizli veriler gereksiz yere tutuluyor mu?
• Başarısız işler için sorumlu kişi ve manuel müdahale prosedürü belli mi?
• Test komutları, migration adımları ve rollback süreci dokümante edildi mi?

Güvenilir bir entegrasyon yalnızca çalışan endpoint’ten ibaret değildir. Olayın yaşam döngüsü, hata davranışı, gözlemlenebilirlik, sürümleme ve bakım sorumluluğu birlikte tasarlandığında SaaS mimarisi daha öngörülebilir ve sürdürülebilir hale gelir.