Webhook Mimarisi Nedir ve Neden Tercih Edilir?

Webhook, bir sistemde belirli bir olay (event) gerçekleştiğinde başka bir sisteme HTTP POST isteği ile anlık veri aktaran mekanizmadır. Geleneksel polling yöntemindeki sürekli sorgu maliyetini ortadan kaldırır. Modern web mimarilerinde asenkron veri akışını optimize eder, sunucu yükünü ve ağ trafiğini düşürür.

Polling veriyi sürekli sorar; webhook ise veri hazır olduğunda hedef sisteme iter. Bu fark, bant genişliği ve CPU tüketimini doğrudan azaltır.

Adım 1: Webhook Payload ve Olay Yapısını Belirleme

Gönderici sistemde olay tetiklendiğinde iletilecek JSON veri şeması netleştirilmelidir. Her yük; olay tipi, zaman damgası ve benzersiz bir kimlik içermelidir.

event: Olayın adı (ör. payment.completed, user.created).
id: Tekil olay kimliği (idempotency kontrolü için UUID).
timestamp: Olayın meydana geldiği Unix epoch zamanı.
data: İlgili nesnenin güncel veri gövdesi.

Adım 2: Webhook Alıcı (Consumer) Uç Noktası Oluşturma

Gelen istekleri işleyen uç nokta hızlı yanıt vermelidir. İstek gövdesini doğrudan senkron işlemek yerine kuyruğa aktarıp 200 OK veya 202 Accepted dönmek gerekir. Ağ zaman aşımı (timeout) hatalarını bu yöntem önler.

Uç Nokta İşlem Akışı:

İsteği al.
İmza doğrulamasını yap (güvenlik).
Payload verisini Redis/RabbitMQ/SQS kuyruğuna yaz.
Anında HTTP 200 yanıtı dön.
Arka plan işçisi (worker) ile veriyi işle.

Adım 3: Güvenlik ve HMAC İmza Doğrulaması

Yetkisiz istekleri ve veri tahrifatını engellemek için HMAC (Hash-based Message Authentication Code) kullanılır. Gönderici, gizli bir anahtar (secret key) ile payload karmasını alır ve X-Signature başlığına ekler. Alıcı aynı karma işlemini tekrarlar ve eşleşmeyi kontrol eder.

Güvenlik uyarısı: Zamanlama saldırılarını (timing attacks) engellemek için dize karşılaştırmasında sabit zamanlı (constant-time) fonksiyonlar (ör. Node.js crypto.timingSafeEqual) kullanılmalıdır.

Adım 4: Yeniden Deneme (Retry) ve Hata Yönetimi Politikası

Alıcı sistem geçici olarak kapalıysa veri kaybını önlemek için gönderici tarafında yeniden deneme mekanizması kurulmalıdır.

Üstel Geri Çekilme (Exponential Backoff): Başarısız istekler 1dk, 5dk, 30dk, 2saat aralıklarla tekrar gönderilir.
Dead Letter Queue (DLQ): Maksimum deneme sayısına ulaşan ve çözülemeyen yükler inceleme için ayrılmış bir hata kuyruğuna aktarılır.
İdempotency: Alıcı, aynı event_id değerine sahip istekleri birden fazla kez alsa dahi işlemi yalnızca bir kez uygulamalıdır.

Dijital Ajans ve SaaS Ekipleri İçin Trendler ve Pratik İpuçları

Sektörel trendler, mikroservislerin ve üçüncü parti SaaS araçlarının entegrasyonunda webhook standartlaşmasını zorunlu kılmaktadır. Bir dijital ajans veya yazılım ekibi için webhook yönetiminde dikkat edilmesi gereken kritik noktalar:

Yerel Geliştirme Testleri: Ngrok veya Cloudflare Tunnels ile yerel sunucuyu dışa açarak harici webhook'ları simüle edin.
İzleme ve Günlük Kaydı (Logging): Gönderilen ve alınan tüm isteklerin başlıklarını, yanıt kodlarını ve sürelerini loglayın.
Standart Şemalar: Sektör genelinde standartlaşan CloudEvents spesifikasyonunu takip edin.

Bu rehber adımları uygulandığında; sistemler arası veri transferi güvenli, hataya dayanıklı ve yüksek performanslı bir yapıya kavuşur.