Webhook Mimarisi Nedir ve Neden Dijital Strateji için Kritik?

Webhook, olay tabanlı (event-driven) sistemler arası veri aktarım mekanizmasıdır. Polling yöntemi gibi belirli aralıklarla sorgu atmak yerine, kaynak sistemde bir olay gerçekleştiğinde hedef sisteme anında HTTP POST isteği gönderir. Modern yazılım mimarilerinde ve dijital strateji süreçlerinde webhook kullanımı; sunucu yükünü azaltır, gerçek zamanlı veri akışı sağlar ve API maliyetlerini düşürür.

Webhook vs Polling: Modern Entegrasyon Trendleri

Geleneksel mimariler sürekli HTTP GET istekleriyle veriyi kontrol eder. Güncel trendler olay güdümlü mimarileri (EDA) öne çıkarır:

Kaynak Tüketimi: Polling %98 oranında boş yanıt döner; webhook sadece veri olduğunda çalışır.
Gecikme Süresi: Polling döngü aralığına bağlı gecikme üretir; webhook anında tetiklenir.
Ölçeklenebilirlik: Webhook mimarisi microservice entegrasyonlarında ağ trafiğini minimize eder.

Adım Adım Webhook Mimarisi Kurulumu (How-To)

Bu rehber, güvenli ve dayanıklı bir webhook altyapısı kurmak için gerekli temel adımları içerir.

Adım 1: Güvenli Alıcı (Consumer) Endpoint Tanımlama

Alıcı sistem, gelen POST yükünü işleyecek bir HTTP endpoint açmalıdır. İstek gövdesi (payload) JSON formatında parse edilir.

Adım 2: HMAC İmza Doğrulama ile Güvenlik Sağlama

Webhook isteklerinin yetkisiz kaynaklardan gelmediğini doğrulamak için HMAC SHA-256 imzası kullanılmalıdır. Gönderici sistem, payload verisini gizli anahtarla (secret) imzalayıp header alanında (örneğin X-Signature-SHA256) iletir.

Node.js stdlib (crypto) ile imza doğrulama örneği:

const crypto = require('crypto');

function verifyWebhook(rawBody, signatureHeader, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = 'sha256=' + hmac.update(rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(digest), Buffer.from(signatureHeader));
}

Güvenlik Uyarısı: Timing attack saldırılarını önlemek için her zaman sabit zamanlı karşılaştırma (timing-safe comparison) fonksiyonları kullanılmalıdır.

Adım 3: Asenkron İşleme ve Kuyruk (Queue) Mimarisi

Webhook endpoint'i gelen isteği doğrudan veritabanında uzun işlemlerle bekletmemelidir. 5 saniyeden uzun süren işlemler timeout hatasına yol açar.

İsteği al.
İmzayı doğrula.
Payload'u Redis/RabbitMQ/SQS gibi bir mesaj kuyruğuna at.
Anında HTTP 200 OK veya HTTP 202 Accepted dön.
Arka plan worker süreçleri ile veriyi işle.

Adım 4: Idempotency (Mükerrer İstek Koruması)

Ağ kesintilerinde webhook sağlayıcıları aynı olayı tekrar gönderebilir (at-least-once delivery). Sisteminizin aynı veriyi iki kez kaydetmemesi için her isteğe ait benzersiz event_id değeri kontrol edilmelidir.

async function handleEvent(event) {
  const exists = await db.processedEvents.find(event.id);
  if (exists) return; // Zaten işlendi, atla
  
  await db.transaction(async (trx) => {
    await processBusinessLogic(event, trx);
    await trx.processedEvents.insert({ id: event.id, processed_at: new Date() });
  });
}

Hata Yönetimi ve Yeniden Deneme (Retry) Stratejileri

Sağlayıcı (Producer) tarafında ise şu kurallar uygulanmalıdır:

Exponential Backoff: Başarısız teslimatlarda bekleme süresi katlanarak artırılmalıdır (ör. 1s, 2s, 4s, 8s).
Dead Letter Queue (DLQ): Maksimum deneme sınırına (ör. 5 deneme) ulaşan başarısız istekler incelenmek üzere DLQ'ya aktarılmalıdır.
Circuit Breaker: Hedef sunucu sürekli 5xx hatası veriyorsa geçici olarak istekler durdurulmalıdır.