API Entegrasyonu Neden Bozulur? Webhook, Retry ve Idempotency Rehberi
API ve webhook akışlarını canlıda dayanıklı kılmak için veri sözleşmesi, tekrar deneme, idempotency ve gözlemlenebilirlik rehberi.
Güncellendi: 9 Ağustos 2026
Önce veri sözleşmesini ve sahipliği yazın
Her alanın adı, tipi, zorunlu olup olmadığı ve hangi sistemin kaynağı olduğu net olmalıdır. Bir müşteri kaydı iki sistemde de değişebiliyorsa, çakışmada hangi değerin kazanacağı önceden belirlenir.
Sözleşmeye hata formatı, sürümleme ve geriye dönük uyumluluk da eklenmelidir. Bu çalışma, sorun çıktığında ekiplerin birbirini suçlaması yerine neyin değiştiğini hızlıca bulmasını sağlar.
Webhook'lar en az bir kez gelebilir
Webhook göndericisi, alıcının cevabını zamanında alamazsa aynı olayı yeniden gönderebilir. Alıcı tarafı olayı hemen kabul edip arka planda işleyebilir; ancak olay kimliğini kaydetmeden aynı siparişi, bildirimi veya kaydı iki kez işlemek güvenli değildir.
Gelen isteğin imzasını doğrulayın, olay kimliğini saklayın ve daha önce işlendi ise güvenli bir başarı yanıtı verin. İşleme süresi uzunsa kuyruğa almak, webhook endpoint'ini daha dayanıklı kılar.
Retry tek başına çözüm değildir
Geçici ağ hatalarında sınırlı ve artan aralıklarla retry işe yarar. Ancak her hatayı tekrar denemek; geçersiz isteği, yetki hatasını veya bozuk veriyi daha da büyütebilir. Hataları geçici, kalıcı ve insan müdahalesi gerektiren olarak ayırın.
Bir ödeme veya kayıt oluşturma işlemi tekrarlandığında aynı sonucu üretmesi gerekir. Idempotency anahtarı, aynı mantıksal isteğin birden fazla kez gelmesi durumunda yeni kayıt açılmasını engeller.
Canlıya çıkmadan önce hata senaryolarını çalıştırın
Test planında sağlayıcı yavaşlığı, timeout, 500 yanıtı, eksik alan, yinelenen webhook, kuyrukta kalan olay ve manuel tekrar işleme bulunmalıdır. Her senaryoda kullanıcıya ne gösterileceği ve ekibin nereden müdahale edeceği bilinmelidir.
İzleme ekranında yalnızca toplam hata sayısı değil, entegrasyon adı, olay kimliği, son deneme zamanı ve sonraki aksiyon görünür olmalıdır. Böylece entegrasyon, sessizce bozulan bir kara kutu olmaktan çıkar.
Sık sorulan sorular
Webhook neden iki kez çalışır?
Gönderici, alıcının cevabını zamanında alamadığında aynı olayı tekrar gönderebilir. Olay kimliği ve idempotent işleme ile tekrar güvenli hale getirilir.
Hangi API hatalarında retry yapılmalı?
Geçici ağ, timeout ve bazı 5xx hataları sınırlı retry için uygundur. 4xx doğrulama veya yetki hataları genellikle düzeltilmeden tekrar denenmemelidir.
Idempotency ne işe yarar?
Aynı mantıksal isteğin tekrar gelmesi durumunda ikinci bir ödeme, kayıt veya aksiyon üretilmesini engeller; ilk sonucun güvenle yeniden kullanılmasını sağlar.