Webhook Mimarisi Nedir?

Webhook, olay tabanlı (event-driven) HTTP geri çağırma (callback) mekanizmasıdır. Polling yöntemi gibi kaynak tüketmez. Bir sistemde durum değiştiğinde, hedef sunucuya JSON yükü içeren HTTP POST isteği fırlatır. Modern web mimarilerinde mikroservisleri ve üçüncü parti servisleri (Stripe, GitHub, CRM) bağlamanın standart yoludur.

Webhook vs Polling: Temel Farklar

Polling: İstemci belirli aralıklarla sunucuya sorar: 'Yeni veri var mı?'. Boşa bant genişliği ve CPU harcar.
Webhook: Sunucu veri oluştuğu anda istemciye gönderir. Trendler gerçek zamanlı ve reaktif mimarilere odaklıdır.

Adım Adım Webhook Mimarisi Kurulumu

Adım 1: Endpoint Tanımlama ve Hızlı Yanıt (HTTP 200/202)

Webhook tüketicisi (consumer) gelen isteği alır almaz zaman aşımını (timeout) önlemek için hemen 200 OK veya 202 Accepted dönmelidir. Ağır iş mantığı doğrudan endpoint içinde çalıştırılmaz.

// Express.js Basit Consumer Örneğiapp.post('/webhooks/payment', (req, res) => {  const signature = req.headers['x-signature-sha256'];  const payload = req.body;  // Doğrulama  if (!verifySignature(payload, signature, process.env.WEBHOOK_SECRET)) {    return res.status(401).send('Geçersiz imza');  }  // İşi kuyruğa at, hemen 202 dön  jobQueue.push(payload);  res.status(202).json({ received: true });});

Adım 2: Güvenlik ve HMAC SHA-256 Doğrulaması

Gelen isteğin yetkili kaynaktan geldiğini garantilemek için paylaşılan gizli anahtar (secret key) ile hash doğrulaması şarttır. Güvenliksiz webhook veri manipülasyonuna yol açar.

Sağlayıcı (Producer), payload içeriğini secret key ile hash'ler (HMAC-SHA256).
Oluşan imzayı HTTP başlığında (Header) iletir.
Tüketici (Consumer), ham payload'ı aynı secret ile yerel olarak hash'ler ve eşleşmeyi kontrol eder (zamanlama saldırılarına karşı crypto.timingSafeEqual kullanılır).

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

Webhook verisi doğrudan veritabanına yazılmaz veya karmaşık işlemlerle bekletilmez. Redis, RabbitMQ veya AWS SQS gibi bir kuyruk sistemine aktarılır. Worker process kuyruktan tüketir.

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

Ağ kesintilerinde sağlayıcı aynı webhook'u birden fazla kez gönderebilir (at-least-once delivery). Tüketici aynı işlemi mükerrer yapmamalıdır.

Her olay için benzersiz bir event_id kullanılır.
İşlenen ID'ler veritabanında veya Redis üzerinde saklanır.
Gelen ID daha önce işlendiyse işlem atlanır, yine 200 OK dönülür.

Adım 5: Retry Mekanizmaları ve Dead Letter Queue (DLQ)

Sağlayıcı tarafında başarısız istekler için Exponential Backoff (üstel geri çekilme) stratejisi uygulanmalıdır (Örn: 1s, 5s, 30s, 5dk sonra tekrar dene). Tüketici tarafında işlenemeyen hatalı paketler analiz için DLQ'ya yönlendirilir.

Dijital Ajans ve Geliştirici Ekipleri İçin Uygulama Stratejileri

Bir dijital ajans veya yazılım ekibi için webhook entegrasyonlarını standartlaştırmak bakım maliyetini düşürür:

Loglama ve İzlenebilirlik: Gelen tüm payload ve header bilgileri merkezi log sistemine (ELK, CloudWatch) yazılmalıdır.
Yerel Test Araçları: Geliştirme ortamında webhook testleri için Ngrok veya LocalTunnel kullanılır.
Retry/Replay Paneli: Hata anında başarısız webhook'ları yeniden tetikleme arayüzü sağlanmalıdır.

Önemli Kural: Webhook uç noktalarınızda her zaman ham gövde (raw body) verisini doğrulayın. JSON parse edilmiş gövde üzerinden yapılan HMAC doğrulamaları, karakter dizilimi farkları nedeniyle başarısız olur.