Webhooks Nedir? 15 Dakikada Güvenli Entegrasyon

Meta Description

Webhooks nedir ve nasıl güvenli kullanılır? İmza doğrulama, retry, idempotency ve Node.js örneğiyle 15 dakikada kurun.

Giriş (Introduction)

Web uygulamalarında “bir şey oldu, anında haberim olsun” ihtiyacı hiç bitmiyor: ödeme alındı, kargo durumu değişti, abonelik yenilendi, kullanıcı kayıt oldu… Bu gibi olayları sürekli API’yi sorgulayarak (polling) yakalamak hem maliyetli hem de gecikmeli.

İşte tam bu noktada webhooks devreye girer. Webhooks, bir olay gerçekleştiğinde karşı tarafa otomatik HTTP isteği göndererek sistemler arası gerçek zamanlı iletişim kurar.

Bu yazıda webhooks nedir sorusunu netleştirip, güvenli ve sağlam bir webhook endpoint’ini adım adım nasıl tasarlayacağınızı; imza doğrulama, idempotency, retry ve loglama gibi “production” detaylarıyla birlikte öğreneceksiniz.

---

Webhooks Nedir? (Temel Mantık)

Webhooks nedir? Kısaca: Bir servis (ör. ödeme sağlayıcısı), belirlenen URL’nize bir olay olduğunda HTTP POST isteği atar.

Polling vs Webhook (Neden webhook?)

Yaklaşım	Nasıl çalışır?	Artı	Eksi
Polling	Belirli aralıklarla API sorgularsınız	Basit	Gecikme + gereksiz trafik
Webhook	Olay olunca servis sizi çağırır	Gerçek zamanlı + düşük maliyet	Güvenlik ve hata yönetimi gerekir

Bunu neden yapmalıyım? Çünkü webhook ile:

• Daha az API çağrısı yaparsınız (maliyet düşer)
• Olayları anlık yakalarsınız (UX artar)
• Entegrasyonlar daha ölçeklenebilir olur

---

Webhook Mimarisi: Gönderen–Alıcı Akışı

Bir webhook entegrasyonunda 3 parça kritik:

1. Event üretici: Stripe, GitHub, iyzico, Shopify vb.
2. Webhook endpoint: Sizin sunucunuzdaki URL (örn. /webhooks/payment)
3. Event işleyici: Kuyruk, worker, DB güncelleme vb.

Tipik akış

1. Sağlayıcı bir “event” oluşturur (örn. payment.succeeded).
2. Sağlayıcı sizin endpoint’inize JSON payload gönderir.
3. Siz isteği doğrular, hızlıca 200 OK dönersiniz.
4. Asıl işi arka planda (queue/worker) işlersiniz.

İpucu: Webhook endpoint’i “iş yapma yeri” değil, “olayı güvenle teslim alma yeri” gibi tasarlanmalıdır.

---

Güvenlik: İmza Doğrulama ve IP/Secret Yönetimi

Webhook’ların en sık yapılan hatası: “URL’yi bilen herkes POST atabilir” gerçeğinin atlanması.

1) Shared secret ile imza doğrulama (önerilen)

Birçok sağlayıcı X-Signature / Stripe-Signature gibi header’lar gönderir. Mantık şudur:

• Payload + timestamp gibi alanlardan HMAC üretilir
• Siz aynı secret ile tekrar üretip karşılaştırırsınız

Aşağıdaki örnek, Node.js (Express) ile HMAC doğrulama mantığını gösterir.

Node.js: Raw body ile HMAC doğrulama

Not: İmza doğrulamada raw body kritik olabilir. JSON parse edildikten sonra boşluk/format değişebilir.

import crypto from "crypto";
import express from "express";

const app = express();

// raw body almak için
app.use(express.raw({ type: "application/json" }));

const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;

function timingSafeEqual(a, b) {
  const bufA = Buffer.from(a);
  const bufB = Buffer.from(b);
  if (bufA.length !== bufB.length) return false;
  return crypto.timingSafeEqual(bufA, bufB);
}

app.post("/webhooks/provider", (req, res) => {
  const signature = req.header("x-signature");
  if (!signature) return res.status(400).send("Missing signature");

  const raw = req.body; // Buffer
  const expected = crypto
    .createHmac("sha256", WEBHOOK_SECRET)
    .update(raw)
    .digest("hex");

  if (!timingSafeEqual(signature, expected)) {
    return res.status(401).send("Invalid signature");
  }

  // Doğrulandı: hızlı yanıt + arka plan iş
  res.status(200).send("OK");

  // burada iş kuyruklayın (ör: SQS/RabbitMQ/BullMQ)
  // enqueueEvent(JSON.parse(raw.toString("utf8")))
});

app.listen(3000, () => console.log("Listening on 3000"));

2) Replay attack önleme (timestamp kontrolü)

Bazı sağlayıcılar imzaya timestamp ekler. Siz de:

• timestamp çok eskiyse (örn. > 5 dk) reddedin.

3) IP allowlist (opsiyonel ama faydalı)

Sağlayıcı sabit IP aralığı veriyorsa, WAF/Nginx seviyesinde allowlist yapabilirsiniz.

4) Secret yönetimi

• Secret’ı kodda tutmayın
• .env + secret manager (AWS Secrets Manager, GCP Secret Manager vb.) kullanın

---

Dayanıklılık: Retry, Idempotency ve Duplicate Event Yönetimi

Webhook dünyasında “aynı event birden fazla gelebilir” normaldir.

1) Retry mantığını kabul edin

Sağlayıcı çoğu zaman:

• 5xx alırsa
• timeout olursa

aynı eventi tekrar gönderir.

2) Idempotency (olmazsa olmaz)

Her event’in bir event_id alanı olduğunu varsayalım. Siz DB’de bu event_id’yi unique tutarsanız:

• Aynı event tekrar gelirse işlenmez
• Sisteminiz çift kayıt oluşturmaz

Basit idempotency tablosu fikri

Alan	Tip	Not
event_id	string (unique)	Duplicate önler
received_at	datetime	İzleme
status	enum	processed/failed

Bunu neden yapmalıyım? Örn. ödeme “başarılı” event’i iki kez gelirse iki kez sipariş oluşturmak çok pahalı bir hata.

---

Performans: Webhook Endpoint’ini Hızlı Tasarlayın

Webhook endpoint’i için altın kural:

• Hızlı doğrula
• Hızlı 200 dön
• Asıl işi kuyruğa at

Önerilen adımlar

1. İmzayı doğrula
2. Event’i “received” olarak kaydet
3. Queue’ya at (worker işleyecek)
4. 200 OK dön

Ne zaman 4xx/5xx dönmeli?

• 4xx: İmza yanlış, payload bozuk → tekrar göndermesi gereksiz
• 5xx: Geçici hata (DB down) → retry faydalı olabilir

---

Lokal Geliştirme: Webhook’u Bilgisayarında Test Etme

Çoğu kişi burada takılır: “Lokalhost’a dışarıdan nasıl webhook gelsin?”

Seçenekler

• ngrok (en popüler)
• Cloudflare Tunnel
• localtunnel

Örnek ngrok akışı

1. Uygulamanı çalıştır: localhost:3000
2. Tünel aç: ngrok http 3000
3. Sağlayıcı panelinde webhook URL’si olarak ngrok URL’sini gir

Gerçek hayattan örnek

Ödeme sağlayıcısıyla entegrasyon yapıyorsunuz:

• Test ödeme alındı
• Sağlayıcı payment.succeeded event’ini webhook ile gönderdi
• Siz siparişi “paid” yaptınız, kargo sürecini başlattınız

Bu akışı lokal ortamda kurmak, yayına almadan önce hataları yakalamanın en hızlı yoludur.

---

Gözlemlenebilirlik: Log, Alarm ve DLQ (Hata Kutusu)

Webhook’lar arka planda aktığı için hatalar sessiz kalabilir.

Minimum öneriler

• Her event için event_id, type, status loglayın
• Başarısız işleme için retry sayısı tutun
• Sürekli fail eden event’leri DLQ (Dead Letter Queue) benzeri bir yere ayırın

Alarm kurun

• Son 15 dakikada 5xx oranı %X’i geçerse bildirim
• “processed” olmayan event sayısı artarsa uyarı

---

Sık Sorulan Sorular (FAQ)

1) Webhooks nedir, API’den farkı ne?

API’de genelde siz çağrı yaparsınız. Webhook’ta olay olduğunda karşı taraf sizin URL’nizi çağırır.

2) Webhook neden iki kez geliyor?

Timeout, 5xx hatası veya ağ problemleri nedeniyle sağlayıcı aynı event’i retry edebilir. Bu yüzden idempotency şarttır.

3) Webhook endpoint’inde neden hemen 200 dönmeliyim?

Uzun süren DB/işlem yüzünden timeout olursa sağlayıcı retry atar. En iyi pratik, doğrulayıp kuyruğa atmak ve 200 dönmektir.

4) İmza doğrulama şart mı?

Evet. Aksi halde endpoint’inize sahte istekler atılabilir. En azından shared secret + HMAC doğrulaması yapın.

5) Webhook’u nasıl test ederim?

ngrok/Cloudflare Tunnel ile lokal URL’nizi internete açın veya sağlayıcının “test event gönder” özelliğini kullanın.

---

Sonuç

Bu yazıda webhooks nedir sorusunu temelden alıp, güvenli ve ölçeklenebilir bir webhook tasarımının kritik parçalarını gördük: imza doğrulama, idempotency, retry yönetimi, hızlı yanıt + kuyruk, ve log/alarmlar.

Şimdi siz de:

• Kullandığınız sağlayıcının (ödeme, e-ticaret, Git) bir test webhook’u açın
• Endpoint’inize imza doğrulama ekleyin
• event_id ile duplicate korumasını uygulayın

Denediğiniz sağlayıcıyı ve karşılaştığınız problemi yorum olarak yazın; birlikte daha sağlam bir akış kuralım.