02.04.2026 10:43:49Uzmanlık yazısı
Event-driven Entegrasyon: Webhook, Mesaj Kuyruğu, Outbox Ve Idempotency İle Güvenilir Kurumsal Mimari
Kurumsal sistemler arasında olay tabanlı entegrasyon: webhook nedir, ne zaman mesaj kuyruğu, transactional outbox ve idempotency ile tekrarlayan teslimatta veri kaybını ve çift işlemi nasıl önlersiniz? Pratik karar çerçevesi ve aksiyon planı.
Hızlı Özet
Event-driven entegrasyon, sistemlerin birbirini beklemeden ama birbirinden kopmadan çalışmasını sağlayan bir dayanıklılık yaklaşımıdır. Klasik “çağır-bekle” modelinde küçük bir kesinti tüm akışı durdurabilir; olay tabanlı modelde ise veri güvenli biçimde taşınır ve işlem daha kontrollü ilerler. Bu sayede webhook, kuyruk, outbox ve idempotency birlikte kullanıldığında kayıp olay ve çift işlem riski belirgin biçimde düşer.
Bu rehber, CRM/ERP ve ödeme akışlarında en çok görülen 3 problemi hedefler: kayıp olay, çift etkiler ve geç fark edilen hatalar.
Bu Yazıda Ne Kazanacaksınız?
• Webhook, kuyruk ve outbox arasında hangi senaryoda hangisini seçmeniz gerektiğini netleştiren karar çerçevesi
• Çift işlem, kayıp olay ve gecikme riskini azaltan idempotency ve hata yönetimi yaklaşımı
• Canlıda kesinti anında ne yapılacağını belirleyen pratik operasyon runbook'u bakışı
Bu rehberin devamındaki bölümler, bu üç çıktıyı adım adım işletmeye nasıl uygulayacağınızı somut örneklerle gösterir.
Event-Driven Entegrasyon Nedir?
Klasik senkron entegrasyon: A sistemi B’yi doğrudan çağırır; B yavaş veya kapalıysa A zaman aşımına düşer, kullanıcı hata görür veya işlem yarım kalır.
Olay tabanlı yaklaşımda: A önce olayı kaydeder veya kuyruğa yazar, arka planda tüketici B (ve diğerleri) kendi hızında işler. Amaç; gevşek bağlantı (loose coupling), yeniden dene (retry) ve ölçeklenebilirlik.
Webhook: Ne Zaman Yeterli, Ne Zaman Riskli?
Webhook, bir sistemde oluşan olayı HTTP çağrısı ile karşı tarafa anında iletmek için kullanılır (ör. ödeme sağlayıcısı “ödeme başarılı” bildirimi).
Uygun olduğu durumlar
• Düşük–orta hacim, sınırlı sayıda abone
• Sağlayıcının webhook modeli iyi dokümante ve imzalı/secret korumalı
• Tüketici tarafında hızlı yanıt ve net hata kodu
Riskler
• Ağ kopması → teslimat kaybı veya gecikme (retry politikası olmadan)
• Karşı sunucunun yavaş olması → zaman aşımı ve üst sistemde birikme
• Aynı olayın birden fazla gönderilmesi (at-least-once) → idempotency şart
Kural: Sadece webhook ile “kritik finansal doğruluk” taşıyorsanız, mutlaka idempotency anahtarı, imza/doğrulama ve işlem günlüğü tasarlayın.
Mesaj Kuyruğu (Message Queue): Neden?
Kuyruk; üretici ile tüketiciyi zaman ve yük açısından ayırır. Mesaj saklanır, tüketici kapalı bile olsa ileti kaybolmaz (platform ayarlarına bağlı), birden fazla worker ile ölçeklenir.
Ne zaman tercih edilir?
• Yüksek hacim veya ani sıçrama (spike)
• Birden fazla tüketici aynı olay türünü dinleyecek (fan-out ayrı tasarım)
• Webhook kaynağı güvenilir değil veya sık yeniden gönderim yapıyor
Dikkat
• Mesaj sırası (ordering) gereksinimi varsa tasarım zorlaşır
• Zehirli mesajlar için dead-letter ve operasyon runbook’u şart
Transactional Outbox: Veri ve Olayın Tutarlılığı
Outbox pattern: İşlem veritabanında (ör. sipariş satırı) ile aynı transaction içinde bir outbox tablosuna “gönderilecek olay” yazılır. Ayrı bir dispatcher bu kayıtları okuyup kuyruğa veya dış API’ye iletir.
Fayda: “Sipariş kaydedildi ama kuyruk mesajı düşmedi” veya tersi durumunu önemli ölçüde engeller.
Özet akış
• Uygulama DB transaction: iş domain kaydı + outbox kaydı
• Relay/dispatcher: outbox’tan oku → publish → başarılı ise işaretle veya sil
• Tüketici: idempotent işle
CRM/ERP entegrasyonlarında sık görülen “ERP’ye düşmedi ama CRM’de var” senaryosunun mimari cevabıdır.
Idempotency: Çift İşlem Neden Olur?
Dağıtık sistemlerde çoğu teslimat at-least-once (en az bir kez) modellenir: ağ, yeniden deneme veya yük dengeleyici aynı isteği iki kez uyar.
Idempotent tüketici: Aynı iş kimliği (ör. `Idempotency-Key`, olay kimliği + kaynak) ile ikinci gelişte yan etki üretmez (yeni sipariş oluşturmaz, stok iki kez düşmez).
Pratik kontrol listesi
• İş anahtarını üreticide veya olay gövdesinde taşıyın
• Tüketicide “bu anahtar işlendi mi?” kontrolü veya doğal tekilleştirme (unique constraint)
• Zaman penceresi ve temizlik (storage maliyeti vs tutarlılık)
Dead-Letter ve Gözlemlenebilirlik
Sürekli hata veren mesajlar ana kuyruğu tıkamamalı; dead-letter queue (DLQ) veya poison handling ile ayrılmalıdır.
Ekip şunları netleştirmeli:
• Kaç yeniden deneme, backoff stratejisi
• DLQ’ya düşen mesaj için alarm ve manuel müdahale
• İzlenebilir correlation id (uçtan uca takip)
Operasyon Runbook'u (Canlı Ortam)
• Olay birikmesi: Kuyruk gecikmesi eşiğini (örneğin 5 dk) aşınca otomatik alarm + sorumlu ekip.
• DLQ patlaması: Son 30 dakikadaki hata türlerine göre ilk ayrım (schema, timeout, auth) ve net aksiyon.
• Tekrarlı teslimat: Idempotency anahtarı hit oranını takip edip beklenmedik artışta kaynak sistemi inceleme.
• Kesinti sonrası toparlama: Replay penceresi, veri doğrulama checklist'i ve rollback karar kriteri.
iPaaS ve Özel Entegrasyon ile İlişki
iPaaS üzerindeki “akışlar” çoğu zaman dolaylı olarak event benzeri tetikler kullanır; fakat kritik çekirdek süreçlerde outbox + kuyruk + idempotency disiplinini uygulama içi veya ayrı bir entegrasyon servisinde tutmak daha güvenli olabilir. iPaaS seçim rehberi ile birlikte okunabilir.
Güvenlik ve Uyumluluk Notları
• Webhook uçları: secret, imza (HMAC), mümkünse IP kısıtlaması
• Olay gövdesinde kişisel veri: minimizasyon, log süreleri (KVKK rehberi ile uyum)
• Yetkilendirme: tüketici API’lerde scope ve rate limit
Karar Özeti (Webhook mu Kuyruk mu Outbox mu?)
| İhtiyaç | Önerilen bileşen |
|---|---|
| Basit harici bildirim, düşük hacim | Webhook + idempotency |
| Yüksek hacim, retry, worker ölçekleme | Mesaj kuyruğu |
| DB ile olayın aynı anda tutarlı olması | Transactional outbox |
| Aynı olayın iki kez gelme riski | Idempotent tüketici + iş anahtarı |
İşletmeler İçin Aksiyon Planı
• 3 kritik olay türünü seçin (ör. sipariş onaylandı, ödeme alındı, stok değişti).
• Her biri için üretici (kim yazar), taşıma (webhook / kuyruk / outbox) ve tüketici (kim işler) şemasını çizin.
• Idempotency anahtarı ve hata/ retry politikalarını yazılı hale getirin.
• DLQ, alarm ve runbook’u tanımlayın.
• Pilot yükte gecikme, çift işlem ve kayıp senaryolarını test edin.
İlgili rehberler
Konu rehberleri (özet çerçeve):
• Dijital dönüşüm ve entegrasyon
• AI otomasyon ve iş süreçleri
• CRM, ERP ve API Entegrasyonu: Kurumsal Otomasyon Rehberi
• iPaaS Nedir? iPaaS mi Özel Entegrasyon mu: Kurumsal Seçim Rehberi
• RPA, API Otomasyonu ve LLM: İş Süreçlerinde Hangi Yaklaşım Ne Zaman?
• Kurumsal AI ve KVKK: Veri Minimizasyonu ve Uyum Çerçevesi
• İş Süreçlerinde AI Otomasyonu: Kurumsal Dönüşüm ve Ölçeklenebilir Uygulama Rehberi
• AI Destekli Web Tasarımı: Dönüşüm Odaklı Kurumsal Site Mimarisi
• Yapay Zeka Destekli Web Uygulaması: Mimari, Veri ve Güvenlik Rehberi
• CRM Veri Kalitesi: Dedupe, Altın Kayıt ve Rapor Tutarlılığı Kurumsal Rehberi
• Kurumsal LLM Maliyet Yönetimi: Cache, Model Seçimi, Rate Limit ve Bütçe Rehberi
Sık Sorulan Sorular
Evet. Örneğin dış sistem webhook gönderir; siz anında işlemek yerine mesajı kuyruğa alıp worker ile işlersiniz (yük ve güvenilirlik için).
Proje uyumu
Bunu güvenli şekilde hayata geçirmek ister misiniz?
Rehberi net kapsam, mimari ve üretime hazır teslimata dönüştürelim.