Webhook ve Event-Driven API Geliştirme Rehberi [2026]

Event-Driven Mimari Nedir?

Geleneksel yazılım sistemlerinde bir bileşen diğerini doğrudan çağırır, yanıt bekler ve ancak yanıt geldikten sonra işlemine devam eder. Bu senkron yaklaşım basit senaryolarda iyi çalışır ancak sistemler büyüdükçe darboğazlara yol açar. Bir servisin yavaşlaması tüm zinciri etkiler.

Event-driven (olay tabanlı) mimari bu sorunu kökten çözer. Bir bileşen bir olay yayınlar, diğer bileşenler bu olayı dinler ve kendi hızlarında tepki verir. Yayıncı, dinleyicinin kim olduğunu bilmek zorunda değildir. Bu gevşek bağlılık (loose coupling), büyük ölçekli dağıtık sistemlerin temel yapı taşıdır.

Olay tabanlı mimarinin üç temel bileşeni vardır:

1. Event Producer (Olay Üretici): Bir durum değişikliği gerçekleştiğinde olayı oluşturan bileşen
2. Event Channel (Olay Kanalı): Olayların iletildiği ara katman, genellikle bir message broker
3. Event Consumer (Olay Tüketici): Olayları dinleyen ve buna göre aksiyon alan bileşen

Bu yaklaşım, mikroservis mimarilerinde servisler arası iletişimin temelini oluşturur. Bir sipariş servisi "siparis_olusturuldu" olayını yayınlar; stok servisi, bildirim servisi ve fatura servisi bu olayı bağımsız olarak işler.

Webhook Mekanizması: Nasıl Çalışır?

Webhook, event-driven mimarinin en basit ve en yaygın uygulamasıdır. Bir sistemde belirli bir olay gerçekleştiğinde, önceden tanımlanmış bir URL'ye HTTP POST isteği gönderilir. Bu istek, olayla ilgili veri yükünü (payload) taşır.

Webhook akışı dört adımda çalışır:

1. Tüketici, sağlayıcı sistemde bir endpoint URL'si kaydeder
2. Sağlayıcı sistemde ilgili olay gerçekleşir (ornegin bir odeme tamamlanir)
3. Sağlayıcı, kayıtlı URL'ye olay verisiyle birlikte HTTP POST gönderir
4. Tüketici, gelen isteği işler ve HTTP 200 yanıtı döner

Webhook Güvenliği

Webhook endpoint'leriniz internete açık olduğundan, güvenlik kritik bir konudur. Gelen isteğin gerçekten beklenen kaynaktan geldiğini doğrulamanız gerekir.

HMAC İmzalama: En yaygın yöntemdir. Sağlayıcı, payload'u gizli bir anahtar (secret) ile hash'ler ve bu imzayı HTTP header'ına ekler. Tüketici aynı anahtarla kendi hash'ini hesaplar ve karşılaştırır. Stripe, GitHub ve Shopify bu yöntemi kullanır.

IP Whitelisting: Webhook isteklerinin yalnızca belirli IP adreslerinden gelmesine izin verir. Bu tek başına yeterli değildir ancak HMAC ile birlikte ek bir güvenlik katmanı sağlar.

Timestamp Doğrulama: Replay saldırılarını önlemek için istek zamanını kontrol eder. Belirli bir süre penceresi dışındaki istekler reddedilir. Genellikle 5 dakikalık bir tolerans yeterlidir.

Retry Stratejileri

Webhook dağıtımı her zaman başarılı olmaz. Ağ sorunları, sunucu hataları veya geçici kesintiler yaşanabilir. Sağlam bir retry (yeniden deneme) stratejisi şarttır.

Exponential Backoff: Her başarısız denemeden sonra bekleme süresini iki katına çıkarır. Ilk deneme 1 saniye, ikinci deneme 2 saniye, üçüncü deneme 4 saniye ve bu şekilde devam eder. Bu yaklaşım, hedef sunucuya aşırı yük binmesini engeller.

Tipik bir retry politikası beş ile sekiz deneme arasında yapılandırılır. Tüm denemeler başarısız olursa olay bir dead letter queue'ya taşınır ve manuel inceleme için saklanır.

Polling vs. Webhook Karşılaştırması

Sistemler arası veri senkronizasyonunda iki temel yaklaşım vardır: polling (düzenli sorgulama) ve webhook (olay bildirimi). Her ikisinin de güçlü ve zayıf yönleri vardır.

Özellik	Polling	Webhook
Veri Güncelliği	Gecikme var (sorgu aralığına bağlı)	Anında bildirim
Sunucu Yükü	Yüksek (gereksiz istekler)	Düşük (sadece olay olduğunda)
Uygulama Karmaşıklığı	Basit	Orta (güvenlik, retry gerekir)
Güvenilirlik	Yüksek (kontrol tüketicide)	Orta (sağlayıcıya bağımlı)
Ölçeklenebilirlik	Düşük	Yüksek
Ağ Trafiği	Yüksek (boş yanıtlar dahil)	Düşük
Hata Yönetimi	Kolay	Karmaşık (idempotency gerekir)
Firewall Uyumluluğu	Sorunsuz (giden istek)	Endpoint açık olmalı (gelen istek)

Polling, küçük ölçekli ve düşük frekanslı senaryolarda makul bir tercihtir. Ancak sistemde saniyede yüzlerce olay gerçekleşiyorsa webhook yaklaşımı hem performans hem de maliyet açısından belirgin üstünlük sağlar. Pratikte birçok sistem her iki yöntemi birlikte kullanır: webhook ana mekanizma olarak çalışır, polling ise kaçırılan olayları yakalamak için yedek olarak devreye girer.

Message Broker Seçimi

Olay tabanlı mimarilerde message broker, üreticiler ile tüketiciler arasındaki trafiği yöneten ara katmandır. Doğru broker seçimi, sistemin performansını ve güvenilirliğini doğrudan etkiler.

Özellik	Apache Kafka	RabbitMQ	Redis Streams	AWS SQS
Throughput	Cok yüksek (milyon/sn)	Yüksek (bin/sn)	Yüksek	Yüksek
Gecikme	Düşük (ms)	Cok düşük (us)	Cok düşük	Orta (ms)
Mesaj Saklama	Uzun süreli (disk)	Tüketilene kadar	Yapılandırılabilir	14 güne kadar
Sıralama Garantisi	Partition bazında	Kuyruk bazında	Tam sıralama	FIFO kuyruklarda
Ölçeklendirme	Yatay (partition)	Dikey + küme	Dikey	Otomatik
Operasyonel Yük	Yüksek	Orta	Düşük	Sıfır (yönetilen)
En Uygun Senaryo	Büyük veri akışları	Görev kuyrukları	Hafif event stream	Bulut-native projeler

Apache Kafka, yüksek hacimli veri akışları için endüstri standardıdır. Olayları disk üzerinde saklar, bu sayede geçmişe dönük tekrar işleme (replay) imkanı sunar. Finans, e-ticaret ve IoT gibi saniyede milyonlarca olay üreten sistemlerde tercih edilir.

RabbitMQ, geleneksel mesaj kuyruğu ihtiyaçları için olgun bir çözümdür. AMQP protokolü üzerinden çalışır ve karmaşık yönlendirme senaryolarını destekler. Görev dağıtımı ve iş kuyruğu senaryolarında güçlüdür.

Redis Streams, hafif event streaming ihtiyaçları için Redis ekosisteminin parçası olarak çalışır. Zaten Redis kullanan projelerde ek altyapı kurma gereksinimini ortadan kaldırır.

AWS SQS, bulut-native projeler için yönetilen bir kuyruk hizmetidir. Altyapı yönetimi gerektirmez ve AWS ekosistemiyle doğal entegrasyon sunar.

Event Sourcing ve CQRS

Event sourcing, sistemdeki her durum değişikliğini bir olay olarak kaydeder. Mevcut durumu doğrudan saklamak yerine, o duruma ulaşan tüm olayların kronolojik bir kaydını tutar. Bir banka hesabını düşünün: bakiye bir sayı olarak saklanmak yerine, tüm yatırma ve çekme işlemleri sırasıyla kaydedilir. Bakiye bu olayların toplamından hesaplanır.

Bu yaklaşımın avantajları belirgindir:

• Tam Denetim İzi: Her değişiklik kaydedilir, kim ne zaman ne yaptı sorusunun yanıtı her zaman mevcuttur
• Zaman Yolculuğu: Sistemin herhangi bir andaki durumuna geri dönülebilir
• Olay Tekrarı: Bir hata düzeltildikten sonra olaylar yeniden oynatılarak doğru durum elde edilebilir
• Analitik: Olay akışı, iş zekası ve analitik sistemleri besler

CQRS (Command Query Responsibility Segregation), event sourcing ile sıklıkla birlikte kullanılır. Yazma (command) ve okuma (query) işlemlerini ayrı modellere böler. Yazma tarafı olayları üretir, okuma tarafı ise bu olaylardan optimize edilmiş görünümler (read model) oluşturur.

Bu ayrım, yazma ve okuma işlemlerini bağımsız olarak ölçeklendirme imkanı verir. E-ticaret sistemlerinde okuma trafiği yazma trafiğinin yüzlerce katı olabilir. CQRS ile okuma katmanını ayrı sunucularda çoğaltmak mümkündür.

Async API Tasarım Desenleri

Asenkron API tasarımı, event-driven sistemlerin dış dünyaya açılan kapısıdır. Birkaç temel desen ön plana çıkar.

Publish-Subscribe (Yayınla-Abone Ol)

Bir olay üretici birden fazla tüketiciye aynı anda ulaşır. Üretici, olayı bir topic'e yayınlar; o topic'e abone olan tüm tüketiciler olayı alır. Bu desen, bir sipariş olayının hem stok, hem bildirim, hem de fatura servisine iletilmesi gerektiğinde kullanılır.

Request-Reply Async

Senkron istek-yanıt modelinin asenkron karşılığıdır. İstemci bir korelasyon ID'si ile istekte bulunur, yanıt ayrı bir kanal üzerinden aynı ID ile döner. Uzun süren işlemler (rapor oluşturma, toplu veri işleme) için uygundur.

Event Notification

Minimal veri taşıyan hafif olaylardır. Olayın kendisi yalnızca "bir şey oldu" bilgisini taşır, tüketici gerekli detayı kaynaktan çeker. Bu yaklaşım, olay boyutunu küçük tutar ve bileşenler arası veri bağımlılığını azaltır.

Event-Carried State Transfer

Event notification'ın tersidir. Olay, tüketicinin ihtiyaç duyacağı tüm veriyi taşır. Tüketicinin kaynağa geri dönmesine gerek kalmaz. Ağ çağrılarını azaltır ancak olay boyutunu artırır.

Idempotency: Tekrarlanan İsteklerin Güvenli Yönetimi

Dağıtık sistemlerde aynı olayın birden fazla kez teslim edilmesi kaçınılmazdır. Ağ zaman aşımları, retry mekanizmaları ve broker tekrar denemeleri aynı olayın mükerrer işlenmesine yol açabilir. Idempotency, aynı işlemin birden fazla uygulanmasının sonucu değiştirmemesini garanti eder.

Uygulama stratejileri arasında en yaygın olanı idempotency key kullanımıdır. Her olay benzersiz bir tanımlayıcı taşır. Tüketici bu tanımlayıcıyı bir veritabanında saklar ve gelen her olayı önce bu kayıtla karşılaştırır. Daha önce işlenmiş bir olay tespit edilirse, işlem atlanır veya mevcut yanıt döndürülür.

Bir ödeme webhook'unu düşünün: aynı ödeme bildirimi iki kez geldiğinde, idempotency kontrolü olmadan müşteriden iki kez ücret alınabilir. Bu, hem finansal hem de itibar açısından ciddi bir risk oluşturur.

Dead Letter Queue ve Hata Yönetimi

Her olay başarıyla işlenemez. Format hatası, iş kuralı ihlali veya kalıcı teknik sorunlar nedeniyle bazı olaylar tüm retry denemelerine rağmen işlenemeyebilir. Dead letter queue (DLQ), bu başarısız olayların güvenli bir şekilde ayrıştırıldığı özel bir kuyruktur.

DLQ stratejisinin temel bileşenleri şunlardır:

• Otomatik Yönlendirme: Belirli sayıda başarısız denemeden sonra olay otomatik olarak DLQ'ya taşınır
• Zenginleştirilmiş Metadata: Hata mesajı, deneme sayısı, son hata zamanı ve orijinal kuyruk bilgisi ile birlikte saklanır
• Alarm Mekanizması: DLQ'daki olay sayısı belirli bir eşiği aştığında operasyon ekibine bildirim gider
• Manuel veya Otomatik Yeniden İşleme: Sorun giderildikten sonra DLQ'daki olaylar tekrar ana kuyruğa aktarılabilir

Etkili bir hata yönetimi, circuit breaker deseni ile desteklenmelidir. Hedef servis sürekli hata döndüğünde, circuit breaker devreyi açar ve belirli bir süre boyunca istek göndermez. Bu, hem kaynak sistemi hem de hedef sistemi korur.

İzleme ve Gözlemlenebilirlik

Event-driven sistemlerde gözlemlenebilirlik, senkron sistemlere kıyasla daha zordur ancak daha kritiktir. Bir olay üretildikten sonra hangi tüketicilerin bunu aldığını, işleme süresini ve olası hataları takip etmek gerekir.

Izleme altyapısının üç temel ayağı vardır:

Distributed Tracing: Bir olayın üretiminden tüketimine kadar tüm yolculuğunu izler. OpenTelemetry gibi araçlar, correlation ID üzerinden farklı servislerdeki logları birbirine bağlar.

Metrikler: Kuyruk derinliği, işleme süresi, hata oranı ve tüketici gecikmesi (consumer lag) gibi ölçümler dashboard'larda görselleştirilir. Kuyruk derinliğinin artması, tüketicilerin yetişemediğinin erken bir göstergesidir.

Yapılandırılmış Loglar: Her olay işleme adımı, olay ID'si, timestamp, servis adı ve sonuç bilgisiyle birlikte loglanır. Bu loglar, sorun analizi sırasında hızlı kök neden tespiti sağlar.

Gerçek Dünya Kullanım Senaryoları

Ödeme Bildirimleri

Bir e-ticaret sitesinde müşteri ödeme yaptığında, ödeme sağlayıcısı (Stripe, iyzico) webhook ile mağazaya bildirim gönderir. Bu bildirim üzerine sipariş onaylanır, stok güncellenir, kargo süreci başlatılır ve müşteriye e-posta gider. Tüm bu işlemler tek bir webhook olayından tetiklenir ve birbirinden bağımsız olarak yürütülür.

CI/CD Pipeline Tetikleme

GitHub veya GitLab'da bir commit push edildiğinde webhook tetiklenir. Bu webhook, CI/CD pipeline'ını başlatır: kod derlenir, testler çalışır, güvenlik taraması yapılır ve başarılı olursa production ortamına deploy edilir. Bu akış tamamen olay tabanlıdır ve insan müdahalesi gerektirmez.

E-Ticaret Envanter Senkronizasyonu

Bir ürünün stok bilgisi değiştiğinde, bu olay tüm satış kanallarına (web sitesi, pazar yerleri, mobil uygulama) eş zamanlı olarak iletilir. Kafka gibi bir broker üzerinden yayınlanan stok güncellemesi olayı, her kanal tarafından bağımsız olarak tüketilir. Böylece bir kanalda satılan ürün diğer kanallarda da anında güncellenir ve fazla satış riski ortadan kalkar.

IoT Veri Akışları

Binlerce sensörden gelen veri, event streaming ile merkezi bir platformda toplanır. Her sensör okuması bir olay olarak Kafka'ya yazılır. Farklı tüketiciler bu akışı analiz eder: biri anomali tespiti yapar, biri uzun vadeli trendleri hesaplar, biri de gerçek zamanlı dashboard'u besler.

Sonuc

Event-driven mimari ve webhook mekanizmaları, modern yazılım sistemlerinin ölçeklenebilir, esnek ve gerçek zamanlı çalışmasını sağlayan temel yapı taşlarıdır. Doğru message broker seçimi, sağlam retry stratejileri, idempotency kontrolü ve kapsamlı izleme altyapısı, bu mimarinin başarılı bir şekilde uygulanmasının ön koşullarıdır.

Ankara merkezli bir yazılım şirketi olan Smart Maple, event-driven mimari tasarımı, webhook entegrasyonları ve message broker implementasyonu konularında uzmanlık sunmaktadır. Yüksek hacimli ve gerçek zamanlı veri akışı gerektiren projelerde, ölçeklenebilir ve güvenilir olay tabanlı sistemler geliştirmektedir.