Webhook Retry ve Dead Letter Queue Nedir? Entegrasyon Hataları Nasıl Yönetilir?

Bir ödeme, sipariş, kargo, CRM veya muhasebe sistemi başka bir uygulamaya webhook gönderdiğinde hedef servis geçici olarak kapalı olabilir, zaman aşımına uğrayabilir ya da payload iş kuralına uymadığı için isteği reddedebilir. Event tek denemede kaybolursa iki sistemin verisi sessizce ayrışır. Her hatayı sınırsız yeniden denemek ise hedef servisi sıkıştırabilir ve aynı işlemi birden fazla kez oluşturabilir.

Dayanıklı entegrasyon, başarısız teslimatı sınıflandırır, uygun aralıklarla sınırlı retry uygular, çift işlemi idempotency ile engeller ve çözülemeyen event’i dead letter queue’ya taşır. Daha sonra event’in nedeni incelenir ve güvenli biçimde replay edilir.

Webhook retry nedir?

Webhook retry, webhook teslimatı veya event işleme adımı başarısız olduğunda aynı event’in belirlenmiş kurallarla yeniden denenmesidir. Temel amaç; kısa süreli ağ problemi, servis kesintisi veya kapasite baskısı gibi zaman içinde düzelebilecek hatalarda event’i kaybetmemektir.

Microsoft, yalnız geçici olması beklenen hataların retry edilmesini ve sürekli hata veren işlemlerde sonlu deneme sayısı ya da circuit breaker kullanılmasını önerir Microsoft Transient Fault Handling. Geçersiz payload veya yetkisiz istek aynı biçimde tekrarlandığında sonuç değişmeyeceği için otomatik retry uygun değildir.

Dead letter queue nedir?

Dead letter queue, normal işleme kuyruğunda belirli sayıda başarısız olan mesajların ayrıldığı özel kuyruktur. Amaç hatalı mesajı silmek değil; ana akışın sürekli tıkanmasını önlemek ve event’i daha sonra inceleyebilmektir.

AWS SQS, mesajın belirlenen maxReceiveCount değerini aşması hâlinde redrive policy üzerinden DLQ’ya taşınmasını destekler AWS SQS Dead-Letter Queues. Google Cloud Pub/Sub da teslimat denemeleri belirlenen aralığa ulaştığında mesajı dead-letter topic’e yönlendirebilir Google Cloud Pub/Sub Dead-Letter Topics.

DLQ bir çöp kutusu değildir. Event’in neden başarısız olduğu, kimin inceleyeceği ve hangi koşulda replay edileceği tanımlanmamışsa hata yalnızca başka bir kuyruğa taşınmış olur.

Webhook teslimat akışı nasıl tasarlanmalıdır?

Webhook endpoint’i bütün iş sürecini senkron tamamlamaya çalışmamalıdır. Önce imza ve temel event yapısı doğrulanır, benzersiz event kimliği kaydedilir ve payload dayanıklı kuyruğa eklenir. Ardından hızlı 2xx yanıtı döndürülür. CRM güncellemesi, stok senkronizasyonu veya bildirim gibi uzun işlemler worker tarafından yürütülür.

GitHub, endpoint’in teslimatı aldıktan sonra 10 saniye içinde 2xx yanıtı vermesini ve uzun işlemlerin asenkron kuyrukta yürütülmesini önerir GitHub Webhook Best Practices. Stripe da karmaşık iş mantığından önce başarılı HTTP yanıtı dönülmesini tavsiye eder Stripe Webhook Documentation.

1. HTTPS isteğini alın ve beklenen event türünü doğrulayın.
2. İmza, zaman damgası ve kaynak kimliğini kontrol edin.
3. Event veya delivery ID’nin daha önce işlenip işlenmediğini sorgulayın.
4. Event’i dayanıklı store ve iş kuyruğuna yazın.
5. Kabul edilen teslimata hızlı 2xx yanıtı verin.
6. Worker iş kuralını idempotent biçimde çalıştırsın.
7. Başarısızlığı retry, kalıcı red veya DLQ olarak sınıflandırın.
8. Teslimat ve işleme sonucunu ayrı durumlarla izleyin.

Hangi hatalar retry edilmelidir?

Retry kararı yalnız HTTP koduna değil, hedef servisin sözleşmesine ve hata gövdesine dayanmalıdır. Yine de aşağıdaki sınıflandırma başlangıç modeli sunar.

Microsoft, 503 yanıtındaki Retry-After gibi servis tarafından verilen bekleme bilgisinin dikkate alınmasını önerir Microsoft Transient Fault Handling.

Exponential backoff ve jitter neden gereklidir?

Başarısız event’i hemen ve sabit aralıkla tekrar göndermek, sorun yaşayan hedef servise ek yük bindirir. Exponential backoff denemeler arasındaki süreyi kademeli artırır. Jitter ise süreye rastlantısallık ekleyerek çok sayıda event’in aynı anda tekrar gönderilmesini önler.

• İlk retry kısa süre sonra yapılabilir.
• Sonraki bekleme aralıkları kademeli artırılır.
• Maksimum bekleme ve toplam retry penceresi belirlenir.
• Jitter ile eş zamanlı retry kümeleri dağıtılır.
• Retry-After değeri varsa politika buna uyarlanır.
• Deneme sayısı event’in kritikliği ve hata türüyle sınırlandırılır.

Microsoft, retry storm antipattern’inde yoğun yeniden denemelerin hedef servisi daha da baskılayabileceğini belirtir Microsoft Retry Storm Antipattern. Circuit breaker sürekli hata veren hedefe çağrıları geçici durdurarak toparlanma alanı sağlar Microsoft Circuit Breaker Pattern.

Idempotency neden zorunludur?

Gönderici ilk denemenin işlenip işlenmediğini her zaman bilemez. Hedef işlem tamamlanmış fakat HTTP yanıtı ağda kaybolmuşsa aynı event tekrar gelir. Idempotency yoksa ikinci teslimat ikinci sipariş, ödeme kaydı veya bildirim oluşturabilir.

Sağlayıcının benzersiz event veya delivery ID’si idempotency anahtarı olarak saklanabilir. GitHub, X-GitHub-Delivery değerinin teslimatı ayırt etmek ve aynı delivery’yi tanımak için kullanılmasını önerir GitHub Webhook Best Practices.

• Event ID için benzersiz veritabanı kısıtı kullanın.
• İşleme kaydını atomik insert veya transaction ile oluşturun.
• Received, processing, succeeded ve failed durumlarını ayırın.
• Oluşan iş kaydını event ID ile ilişkilendirin.
• Replay sırasında aynı idempotency bağlamını koruyun.
• İlk deneme yarıda kaldıysa güvenli devam noktası tanımlayın.

Webhook retry ile queue retry aynı şey mi?

Delivery retry, gönderici sistemin webhook endpoint’ine yeniden ulaşmasıdır. Processing retry ise endpoint’in kabul ettiği event’in iç sistemde tekrar işlenmesidir. İki katman ayrı izlenmelidir.

Event kuyruğa yazılmadan 2xx dönülürse gönderici teslimatı başarılı sayar, fakat event iç sistemde kaybolabilir. Kabul yanıtı dayanıklı kayıt tamamlandıktan sonra dönmelidir.

Event ne zaman DLQ’ya taşınmalıdır?

• Maksimum retry sayısı veya toplam retry süresi aşıldığında
• Payload şeması ya da iş kuralı kalıcı biçimde geçersiz olduğunda
• Mapping, yetki veya credential müdahalesi gerektiğinde
• Event sırası bozulduğu için otomatik çözüm güvenli olmadığında
• Veri bütünlüğü riski insan onayı gerektirdiğinde
• Worker aynı deterministik hatayı tekrarladığında

AWS, DLQ saklama süresinin kaynak kuyruktan daha uzun tutulmasını önerir AWS SQS Dead-Letter Queues. Saklama sonunda sessizce silinen event’ler için alarm ve imha politikası bulunmalıdır.

DLQ içindeki event nasıl incelenmelidir?

Operasyon paneli yalnız ham JSON göstermemelidir. Event kaynağı, türü, ilk ve son deneme zamanı, deneme sayısı, son hata sınıfı, tenant ve korelasyon kimliği anlaşılır biçimde sunulmalıdır. Hassas alanlar maskelenmelidir.

1. Event’in kaynağının ilk teslimatta doğrulandığını kontrol edin.
2. Önceki retry hatalarıyla son hatayı karşılaştırın.
3. Bağımlı sistem ve credential durumunu doğrulayın.
4. Event’in kısmen işlenip işlenmediğini idempotency kaydından inceleyin.
5. Payload ile güncel veri sözleşmesini karşılaştırın.
6. Benzer event’lerin toplu hata verip vermediğini araştırın.
7. Replay öncesinde yan etki ve geri dönüş yolunu belirleyin.

Replay nasıl güvenli yapılır?

Replay, başarısız event’in işleme akışına yeniden alınmasıdır. Kontrolsüz toplu replay hedef sisteme yük bindirebilir veya artık geçerli olmayan iş kararlarını çalıştırabilir.

• Replay yetkisini sınırlı role verin ve audit kaydı oluşturun.
• Orijinal payload’ı değiştirmeden koruyun.
• Dönüşüm gerekiyorsa yeni replay sürümü ve gerekçesi kaydedin.
• Idempotency anahtarını koruyun.
• Toplu replay’de rate limit ve batch boyutu kullanın.
• Önce küçük örnek grupta doğrulama yapın.
• Sonucu başarılı, yeniden başarısız veya atlandı olarak kaydedin.

AWS SQS redrive, DLQ mesajlarını kaynak veya farklı bir kuyruğa kontrollü biçimde taşıyabilir AWS SQS DLQ Redrive. Platform özelliği kullanılsa da uygulama idempotency ve iş geçerliliğini doğrulamalıdır.

Event ordering nasıl korunmalıdır?

Bazı entegrasyonlarda sıra önemlidir. “Sipariş oluşturuldu” işlenmeden “sipariş iptal edildi” gelirse ikinci event hedef kaydı bulamayabilir. Ordering key, kaynak versiyon numarası veya sequence değeri kullanılabilir. Sıra bütün sistem yerine aynı sipariş, müşteri veya hesap anahtarı içinde korunabilir.

Eski event, daha yeni durumu geriye çevirmemelidir. Sağlayıcının ordering ve delivery garantileri API entegrasyon hizmeti tasarlanırken doğrulanmalıdır.

Operasyon panelinde hangi bilgiler olmalıdır?

Hangi metrikler izlenmelidir?

• Event türüne göre teslimat hacmi
• 2xx, 4xx, 5xx ve timeout oranları
• İlk deneme ve retry sonrası başarı oranı
• Retry kuyruğu derinliği ve en eski event yaşı
• DLQ event sayısı ve en eski DLQ kaydının yaşı
• Alım ile işleme arasındaki uçtan uca gecikme
• Duplicate ve idempotency ile atlanan event sayısı
• Replay başarı ve yeniden başarısızlık sonucu
• İmza doğrulama hataları

Normal retry ile kısa sürede düzelen tek hata her zaman alarm gerektirmez. DLQ büyümesi, event yaşının iş hedefini aşması veya kritik ödeme event’inin işlenememesi daha yüksek öncelik gerektirir.

Güvenlik ve kişisel veri nasıl yönetilmelidir?

Webhook endpoint’i internetten gelen veri giriş noktasıdır. İmza doğrulanmalı, HTTPS kullanılmalı, payload boyutu sınırlandırılmalı ve beklenmeyen event türleri reddedilmelidir. Event kimliği ile zaman damgası replay saldırılarına karşı kontrol edilmelidir.

DLQ ve operasyon paneli kişisel veri veya ticari sır içerebilir. KVKK, kişisel verilerin hukuka aykırı erişimini önlemek ve muhafazasını sağlamak için teknik ve idari tedbir alınmasını öngörür KVKK Veri Güvenliğine İlişkin Yükümlülükler. Gereksiz alanlar saklanmamalı, erişim sınırlandırılmalı ve retry/DLQ saklama süresi tanımlanmalıdır.

Türkiye ve Samsun bağlamında hata yönetimi

Webhook retry ve DLQ için Samsun’a özgü ayrı bir teknik yöntem gerekmez. Yerel bağlam; entegrasyonun bağlandığı muhasebe, ERP, kargo, ödeme, stok veya CRM süreçlerinden ve payload içindeki verinin hukuki niteliğinden doğar.

Webioo’nun resmî API entegrasyon sayfası; farklı yazılım, ERP, CRM, ödeme, kargo ve raporlama sistemleri arasında veri akışının ve kritik süreçlerin analiz edildiğini belirtir Webioo API Entegrasyon Hizmeti. İş süreci otomasyonu sayfasında kullanıcı rolleri, veri kaynakları, onay kuralları ve entegrasyon gereksinimlerinin analiz edildiği açıklanır Webioo İş Süreci Otomasyonu.

Webioo’nun resmî sitesinde şirket Samsun merkezli yazılım ve dijital dönüşüm ajansı olarak tanımlanır Webioo Resmî Sitesi. Kamuya açık sayfalarda belirli bir müşteriye ait retry sayısı, DLQ hacmi veya performans sonucu doğrulanmadığı için bu içerikte böyle bir proje iddiası kullanılmamıştır.

Sık yapılan hatalar

• Bütün 4xx ve 5xx yanıtlarını aynı politikayla tekrar etmek
• Backoff ve jitter olmadan retry storm oluşturmak
• Idempotency olmadan duplicate işlem üretmek
• Event kuyruğa yazılmadan 2xx dönmek
• DLQ’yu izlememek ve event’leri sessizce kaybetmek
• Replay sırasında event kimliğini değiştirmek
• Eski event’in yeni durumu geriye çevirmesine izin vermek
• Payload içinde token ve gereksiz kişisel veri saklamak
• Delivery ile processing hatasını aynı durum alanında birleştirmek
• Toplu replay için rate limit koymamak

Webhook hata dayanıklılığı kontrol listesi

1. Sağlayıcının timeout, retry, signature ve redelivery davranışını doğrulayın.
2. İmza, zaman damgası ve event türü kontrolü yapın.
3. Event’i dayanıklı kuyruğa aldıktan sonra hızlı 2xx dönün.
4. Benzersiz event veya delivery ID ile idempotency uygulayın.
5. Geçici ve kalıcı hata sınıflarını tanımlayın.
6. Exponential backoff, jitter ve maksimum retry penceresi kullanın.
7. Retry sınırını aşan event’leri DLQ’ya taşıyın.
8. DLQ için sahiplik, alarm ve saklama süresi belirleyin.
9. Replay’i yetkili, audit edilen ve oran sınırlı yapın.
10. Ordering ve eski event geçerliliğini kontrol edin.
11. Delivery ve processing metriklerini ayrı izleyin.
12. Retry, DLQ ve replay senaryolarını iş süreci otomasyonu testlerine ekleyin.

Sonuç: Entegrasyon hatasını kayıp event’e dönüştürmeyin

Webhook retry geçici teslimat ve işleme hatalarında event’i kontrollü biçimde yeniden dener. Exponential backoff ve jitter hedef servisi korur; idempotency aynı event’in çift işlem üretmesini engeller. Retry ile çözülemeyen event’ler dead letter queue’ya ayrılır.

Dayanıklı entegrasyon için DLQ izlenmeli, hata nedeni anlaşılır biçimde gösterilmeli ve replay güvenli yönetilmelidir. Amaç her event’i sonsuza kadar tekrar etmek değil; geçici hatayı otomatik düzeltmek, kalıcı hatayı görünür kılmak ve veri akışını kanıtlanabilir biçimde yeniden başlatmaktır. Bu yaklaşım yazılım geliştirme ve entegrasyon operasyonunun kalıcı parçası olmalıdır.