Webhook Mimarisi: Asenkron Bildirim ve Yeniden Deneme

Hızlı Özet (TL;DR)

Webhook; bir yazılım sisteminde gerçekleşen kritik bir iş olayının (örneğin sanal POS ödemesinin onaylanması, e-Faturanın GİB tarafından kabul edilmesi, üretim hattında bir iş emrinin tamamlanması veya kargo durumunun değişmesi) diğer bir bağımsız sisteme HTTP POST isteğiyle gerçek zamanlı olarak iletilmesini sağlayan olay güdümlü (Event-Driven) “ters API” mimarisidir. Sistemlerin birbirine saniyede bir “yeni bir kayıt var mı?” diye sorması (Polling) ihtiyacını ortadan kaldırır. Ancak kurumsal ölçekte, sıfır veri kaybıyla çalışan bir webhook altyapısı inşa etmek; kriptografik HMAC-SHA256 imza doğrulamasını, zaman damgası (Replay Attack) korumasını, hedef sunucu kapalıyken devreye giren Exponential Backoff + Jitter yeniden deneme mekanizmasını ve mükerrer kayıt oluşumunu engelleyen Idempotency (Eş-etkililik) mimarisini zorunlu kılar.

Neden Geleneksel Polling (Sürekli Sorgulama) Mimarisi Ölçeklenemez?

Bir üretim işletmesinde B2B bayi portalı, e-ticaret sitesi, WMS depo yazılımı ve merkez İmalat ERP Çözümleri sisteminin birbiriyle konuştuğunu düşünelim. Geleneksel entegrasyon yaklaşımında (Polling), ERP sunucusu her 1 dakikada bir bayi portalına bağlanarak “Yeni sipariş var mı?” diye bir REST/SOAP sorgusu gönderir.

Günde 1.440 kez yapılan bu sorguların belki 1.400 tanesi “Hayır, yeni veri yok” cevabıyla boş döner. Entegre edilen sistem ve bayi sayısı 100’e çıktığında, sunucular ortada hiçbir gerçek iş olayı yokken günde yüz binlerce gereksiz veritabanı sorgusu (SQL SELECT) ve HTTP el sıkışması (TLS Handshake) yapmak zorunda kalır. Daha kötüsü, veri senkronizasyonu hiçbir zaman tam gerçek zamanlı olamaz; periyot 5 dakika ise müşteri ödemeyi yaptıktan sonra ortalama 2,5 ila 5 dakika boyunca işleminin onaylanmasını bekler.

Webhook mimarisi ise bu iletişimi tersine çevirir: “Bana sürekli sorma, bir olay gerçekleştiğinde ben sana haber veririm.” Olay gerçekleştiği milisaniyede kaynak sistem, hedef sistemin önceden kaydettiği URL adresine (Callback Endpoint) olayın JSON yükünü (Payload) iter (Push).

Webhook ve Polling Mimarilerinin Teknik Karşılaştırması

İki kurumsal yazılım arasındaki veri senkronizasyonunda geleneksel Polling ile olay güdümlü Webhook mimarisinin karşılaştırması:

Değerlendirme Kriteri	Geleneksel Polling (Zamanlanmış Sorgulama)	Kurumsal Webhook Mimarisi (Olay Tabanlı Bildirim)
İletişim Gecikmesi (Latency)	Ortalama periyodun yarısı (Örn: 5 dk periyotta 2,5 dakika gecikme)	50 – 250 Milisaniye (Olay gerçekleştiği anda anlık tetikleme)
Ağ ve Veritabanı Yükü	%95 – %99’u boş dönen milyonlarca gereksiz HTTP ve SQL sorgusu	Yalnızca durum değiştiğinde tek bir hedef odaklı HTTP POST çağrısı
Sistem Ölçeklenebilirliği	Entegre uç nokta sayısı arttıkça veritabanı bağlantı havuzu tıkanır	Asenkron mesaj kuyrukları (RabbitMQ / Redis Streams) ile yatay ölçeklenir
Tüketici (Alıcı) Gereksinimi	Dışarıya port açması gerekmez, kendisi dışarıya istek atar	Güvenli ve dış dünyadan erişilebilir bir HTTPS uç noktası sunmalıdır
Hata Toleransı ve Veri Kaybı	Bağlantı koparsa bir sonraki periyotta doğal olarak tekrar sorgulanır	Göndericide Exponential Backoff Retry ve Dead Letter Queue (DLQ) şarttır
Mükerrer İşlem Riski	Son okunan ID/Tarih (Cursor) doğru tutulursa düşüktür	Ağ zaman aşımlarında aynı olay 2 kez gelebilir; Idempotency Key zorunludur

Güvenlik Katmanı: HMAC-SHA256 İmza Doğrulaması ve Replay Koruması

Webhook alıcı uç noktası (https://api.sirketiniz.com/webhooks/odeme-onay) doğası gereği dış internete açık bir URL’dir. Eğer bu uç noktada yalnızca IP kısıtlamasına güvenilirse veya hiçbir doğrulama yapılmazsa, kötü niyetli bir saldırgan bu adrese sahte bir {"siparisId": 1054, "durum": "ODENDI"} JSON paketi göndererek bedelsiz ürün sevkiyatı tetikleyebilir.

Bu güvenlik açığını tamamen kapatmak için HMAC (Hash-based Message Authentication Code) ve Zaman Damgası (Timestamp) birleşimi kullanılır:

1. Gönderici Tarafında Kriptografik İmza Üretimi

Gönderici sistem ve alıcı sistem arasında yalnızca iki tarafın bildiği yüksek entropili bir gizli anahtar (WEBHOOK_SECRET) paylaşılır. Gönderici sistem, göndereceği ham JSON metnini (Raw Body) ve o anki Unix zaman damgasını birleştirerek SHA-256 algoritmasıyla imzalar:

// Gönderici ve Alıcı tarafında güvenli HMAC-SHA256 doğrulama mantığı
const crypto = require('crypto');

function dogrulaWebhookImzasi(hamGovde, gelenImza, gelenZamanDamgasi, gizliAnahtar) {
  // 1. Replay Attack Koruması: İstek 5 dakikadan (300 sn) eskiyse reddet
  const simdi = Math.floor(Date.now() / 1000);
  if (Math.abs(simdi - Number(gelenZamanDamgasi)) > 300) {
    return false;
  }

  // 2. Zaman damgası ve ham gövdeyi birleştirerek beklenen imzayı hesapla
  const imzalanacakVeri = `${gelenZamanDamgasi}.${hamGovde}`;
  const beklenenImza = crypto
    .createHmac('sha256', gizliAnahtar)
    .update(imzalanacakVeri, 'utf8')
    .digest('hex');

  // 3. Timing Attack (Zamanlama Saldırısı) önlemli güvenli karşılaştırma
  return crypto.timingSafeEqual(
    Buffer.from(beklenenImza, 'hex'),
    Buffer.from(gelenImza, 'hex')
  );
}

2. Neden timingSafeEqual ve Zaman Damgası Şarttır?

Standart === operatörüyle dizge (String) karşılaştırması yapıldığında, ilk farklı karakterde işlem sonlanır. Gelişmiş saldırganlar yanıt sürelerindeki mikrosaniyelik farkları ölçerek imzayı karakter karakter tahmin edebilir (Timing Attack). crypto.timingSafeEqual fonksiyonu ise tüm baytları sabit sürede karşılaştırarak bu riski ortadan kaldırır. Ayrıca X-Webhook-Timestamp kontrolü sayesinde, ağ dinlemesiyle (Sniffing) ele geçirilmiş geçerli bir paketin saatler sonra tekrar gönderilmesi (Replay Attack) engellenir.

Asenkron Kuyruk, Exponential Backoff ve Jitter ile Yeniden Deneme

Dağıtık sistemlerin birinci kuralı şudur: Ağ güvenilmezdir ve hedef sunucular mutlaka bir gün geçici olarak çöker. Webhook gönderdiğiniz anda karşı tarafın ERP sunucusu bakımda olabilir, veritabanı kilitlenmiş olabilir veya TLS sertifikası yenileniyor olabilir.

Eğer webhook gönderimini doğrudan ana kullanıcı isteğinin (HTTP Request Thread) içinde senkron olarak yaparsanız, karşı sunucu yavaşladığında kendi sisteminiz de kilitlenir. Ayrıca hata alındığında saniyede 100 kez anında tekrar denemek (Immediate Retry), yeni ayağa kalkmaya çalışan hedef sunucuya kendi elinizle DDoS saldırısı yapmak (Thundering Herd Problemi) anlamına gelir.

Kurumsal mimaride uygulanan doğru yeniden deneme stratejisi Exponential Backoff + Rastgele Jitter planıdır:

1. 1. Deneme (Anlık): Olay kuyruğa düştüğü anda (t = 0 sn) gönderilir. Hedef 2xx (200 OK / 202 Accepted) dönerse görev kapanır.
2. 2. Deneme: 5xx sunucu hatası veya zaman aşımı alınırsa 1 dakika (60 sn + ±10 sn rastgele jitter) beklenir.
3. 3. Deneme: Başarısız olursa 5 dakika sonra tekrar denenir.
4. 4. Deneme: Başarısız olursa 30 dakika sonra tekrar denenir.
5. 5. Deneme: Başarısız olursa 2 saat sonra tekrar denenir.
6. 6. ve Son Deneme: 12 saat sonra son kez denenir.

Tüm denemelere rağmen teslim edilemeyen mesajlar silinmez; Ölü Mektup Kuyruğuna (Dead Letter Queue - DLQ) taşınır, devre kesici (Circuit Breaker) ilgili uç noktayı pasife alır ve sistem yöneticilerine uyarı e-postası/SMS gönderilir. Hedef sistem onarıldığında yönetim panelindeki “DLQ Mesajlarını Tekrar Oynat (Replay)” butonuyla tek bir veri bile kaybolmadan akış tamamlanır.

Idempotency (Eş-Etkililik): Aynı İsteğin İki Kez İşlenmesini Önlemek

Webhook dünyasında “En Az Bir Kez Teslimat” (At-Least-Once Delivery) garantisi hedeflenir. Ancak bu durum şu senaryoyu doğurur: Gönderici sistem webhook’u gönderir, alıcı sistem siparişi veritabanına yazar ve stoktan düşer; fakat tam 200 OK cevabını dönerken ağ bağlantısı kopar. Gönderici sistem cevap alamadığı için isteğin başarısız olduğunu varsayar ve 1 dakika sonra aynı webhook paketini tekrar gönderir.

Eğer alıcı sistemde Idempotency (Eş-etkililik) kontrolü yoksa, aynı sipariş iki kez oluşturulur, müşteriden iki kez bakiye düşülür veya Stok Takip ve Barkodlu Depo Yazılımı tarafında mükerrer sevkiyat emri açılır.

Bunu önlemek için her webhook paketinde benzersiz bir event_id (UUID v4/v7) bulunur:

• Alıcı sunucu isteği aldığında önce veritabanındaki ProcessedWebhookEvents tablosunda veya Redis önbelleğinde bu event_id değerini (UNIQUE INDEX kısıtlamasıyla) sorgular.
• Eğer bu ID daha önce işlenmişse, iş mantığını tekrar çalıştırmaz; doğrudan 200 OK (Already Processed) yanıtı dönerek göndericiyi susturur.
• Ayrıca alıcı uç nokta, karmaşık PDF oluşturma veya uzun ERP hesaplamalarını HTTP isteği içinde bekletmemeli; paketi doğrular doğrulamaz kendi iç kuyruğuna atıp 50 milisaniye içinde 202 Accepted yanıtı dönmelidir (Fast ACK).

Kurumsal sistemler arası kayıpsız webhook mimarileri, B2B e-ticaret köprüleri, Üretim Takip Yazılımı olay bildirimleri ve yüksek trafikli API entegrasyonları kurmak için Özel Yazılım Geliştirme sayfamızı inceleyebilirsiniz.

Sıkça Sorulan Sorular

Hedef sunucu 400 Bad Request veya 422 Unprocessable Entity hatası dönerse yeniden deneme (Retry) yapılmalı mıdır?

Hayır, yeniden deneme mekanizması yalnızca 5xx (500, 502, 503, 504) sunucu hatalarında, ağ bağlantı kopmalarında (Connection Refused / Timeout) ve 429 Too Many Requests durumlarında çalıştırılmalıdır. 400, 401 veya 422 gibi 4xx istemci hataları, gönderilen JSON şemasının hatalı olduğunu veya kimlik doğrulamanın geçersiz olduğunu gösterir; aynı hatalı paketi 10 kez tekrar göndermek sonucu değiştirmeyeceği için doğrudan hata loguna düşürülmelidir.

Webhook olaylarının hedefe yanlış sırayla (Out-of-Order) ulaşması sorunu nasıl çözülür?

Ağ gecikmeleri veya ilk isteğin zaman aşımına uğrayıp ikinci isteğin anında geçmesi nedeniyle, siparis.iptal_edildi olayı hedefe siparis.olusturuldu olayından birkaç saniye önce ulaşabilir. Bu “Yarış Durumu”nu (Race Condition) önlemek için her olay yüküne monoton artan bir sequence_number (Sıra Numarası) veya olay zaman damgası eklenir; ya da webhook içinde tüm veriyi taşımak yerine yalnızca olay kimliği gönderilerek alıcı sistemin en güncel durumu ana API’den çekmesi (Thin Payload Pattern) sağlanır.

Müşterilerimizin güvenlik duvarı (Firewall) gelen webhook isteklerini engelliyorsa nasıl bir yapı kurulmalıdır?

Kurumsal müşterilerin iç ağlarındaki güvenlik duvarları yalnızca belirli IP adreslerinden gelen bağlantılara izin verir. Bu nedenle webhook gönderici mimarimiz, dinamik bulut IP’leri yerine sabit (Statik) çıkış IP’lerine sahip bir NAT Gateway / Egress Proxy üzerinden çıkış yapar. Böylece karşı tarafın IT ekibi yalnızca bizim tanımlı 2 adet statik IP adresimizi beyaz listeye (Whitelist) alarak güvenli iletişimi başlatabilir.