Webhook Mimarisi 2026: Retry, Idempotency, Signature ve Svix/Hookdeck Pratiği

Webhook’lar, modern SaaS entegrasyonlarının görünmez kahramanları. Stripe, GitHub, Slack, Shopify gibi platformlar günlük milyarlarca webhook teslim ediyor. Buna karşın çoğu uygulama webhook’ları “POST endpoint, JSON parse” düzeyinde işliyor — sonuç: %3-8 oranında kayıp event, duplicate processing, güvenlik açıkları ve kötü onboarding deneyimi. Doğru tasarlanmış bir webhook altyapısı (retry, idempotency, dead letter, signature verification) güvenilirliği %99,99 seviyesine çıkarır. Türkiye’de webhook tabanlı entegrasyonlar fintech ödeme bildirimleri, e-ticaret order sync ve SaaS partner entegrasyonlarında baskın iletişim deseni.

Bu rehberde, gelen ve giden webhook’lar için referans mimariyi, kullanılan platformları (Svix, Hookdeck, kendi yazımı), Türkiye özelinde notları ve üretim hatalarından çıkarılan dersleri somut sayılarla aktaracağız.

Webhook Mimarisi: İki Yön

• Inbound (gelen): Stripe, GitHub vb. bize HTTP POST gönderir. İmza doğrulanır, işlenir.
• Outbound (giden): Bizim ürünümüz müşteri sistemlerine event POST’lar. Retry + dead letter + signature gerekir.

Webhook, eventually consistent bir push iletişim modelidir; event-driven architecture rehberimizde Kafka/Pulsar gibi internal event streamlerle olan farkı detaylandırıyoruz. API mimari kararı için REST GraphQL Webhook karşılaştırması başvurulabilir.

Inbound Webhook: Doğru Akış

1. İmza Doğrulama

HTTP request body üzerinde HMAC-SHA256 imzası gönderici tarafından imzalanır. Alıcı aynı secret ile yeniden hesaplar ve karşılaştırır. Aksi halde başkası sahte webhook gönderebilir.

• Stripe: Stripe-Signature header’da t=...,v1=....
• GitHub: X-Hub-Signature-256 header.
• Custom: X-Webhook-Signature + X-Webhook-Timestamp.
• Timestamp tolerans: ±5 dk (replay attack engeli).

2. Hızlı 200 Dönmek

Webhook senderlar genelde 5-30 saniye bekler. İşlemini yapmadan önce hemen 200 OK dön. İş kuyruğa alınır (Redis/SQS/RabbitMQ), asenkron worker’larda işlenir.

• Endpoint: imza doğrula → queue’ya bas → 200 OK dön. Toplam < 100 ms.
• Worker: queue’dan oku → idempotency check → business logic → mark processed.
• Eğer queue dolarsa (>10K backlog) alarm.

3. Idempotency

Sender bazen aynı webhook’u 2-3 kez gönderir (timeout, retry). Aynı event 2x işlenirse iki kez para çekilir, iki kez email atılır, vb. Idempotency key şart:

• Stripe: event.id.
• Generic: hash(payload) + timestamp.
• İşlem: Redis SET with NX + TTL (24-72 saat).
• Eğer key zaten var: skip ve 200 OK.

4. Sıralı İşleme (Ordering)

Webhook’lar her zaman sırayla gelmez. Stripe “subscription.updated” iki kez gönderebilir, eski olanı sonradan ulaşabilir. Çözüm:

• Event içindeki version/timestamp ile last-write-wins.
• “Eğer DB’deki version > webhook version → skip”.
• Critical operations için sender’dan tam state çek (örn. Stripe API’dan invoice’ı yeniden GET).

Outbound Webhook: Üretim Pratikleri

Müşteri sistemlerine event göndermek inbound’tan çok daha karmaşık. Çünkü müşterinin sistemi:

• Yavaş olabilir (timeout).
• Çökmüş olabilir (5xx).
• Yanlış URL girilmiş olabilir.
• Authorization sertifikası geçersiz olabilir.
• Rate limit’i olabilir.

Retry Stratejisi

Endüstri standardı: exponential backoff. Tipik tablo:

Attempt	Bekleme	Toplam Süre
1	0	0
2	30 sn	30 sn
3	2 dk	2,5 dk
4	10 dk	12,5 dk
5	30 dk	42,5 dk
6	2 saat	2 saat 42 dk
7	5 saat	7,7 saat
8	1 gün	1,3 gün
9	2 gün	3,3 gün

4xx hatalarda retry yapma (müşteri konfigürasyonu yanlış). 5xx ve timeout için retry. Toplam 9 deneme sonrası dead letter. Rate limit tasarımı için rate limiting stratejileri rehberimize bakabilirsiniz.

Müşteriye Dashboard

• Hangi webhook’lar başarısız oldu.
• Manual replay (tek webhook’u yeniden gönder).
• Bulk replay (son 24 saatin başarısızlarını).
• İmza secret rotation.
• Birden çok endpoint (production + staging).
• Event filtering (sadece istediği event’leri al).

SaaS Webhook Platformları

Platform	Özellik	Maliyet
Svix	Outbound webhook’u tek API’la — retry, signature, dashboard	50-500 USD/ay (10K-1M event)
Hookdeck	Inbound webhook gateway — debug, replay, transformation	49-499 USD/ay
Knock	Customer notifications + webhook	99-999 USD/ay
Webhook Relay	Self-hosted, basit	Açık kaynak
Kendi yazımı	Tam kontrol	50-200K TL geliştirme + 5-15K TL/ay altyapı

Svix Detay

• Outbound webhook’lar için Stripe’ın çözümünü kullanan altyapı.
• HMAC signature otomatik (kendi secret yönetir).
• Exponential backoff built-in.
• Dashboard, replay, secret rotation hepsi out-of-the-box.
• Müşteri başına billing dahil.
• Customer-facing UI (kendi marka rengi ile).

Inbound Mimarisi: Kendi Yazımı

• API Gateway: Nginx/Envoy → uygulama (max 100 ms response).
• Queue: Redis Stream veya SQS veya Kafka.
• Worker: 5-20 paralel consumer, prefetch 10.
• Idempotency store: Redis (TTL 72 saat).
• DLQ (Dead Letter Queue): 9 deneme sonrası buraya.
• Monitoring: Backlog, success rate, p99 processing time.

Güvenlik Listesi

• HMAC signature zorunlu (her webhook’ta).
• Timestamp ±5 dakika tolerans (replay attack).
• Sadece HTTPS endpoint kabul (HTTP/HTTPS karışıklığı yok).
• Rate limiting (gönderici başına saniyede max 100).
• IP allowlist (Stripe gibi sabit IP’lerden gelenler için).
• Payload boyut limiti (≤ 1 MB).
• Body parse hatası 4xx (DLQ yok).

Türkiye Özelinde Pratik Notlar

• Bankacılık/finans bildirimleri: Iyzico/Param/PayTR webhook’ları için imza doğrulama + idempotency kritik; çift ödeme riskli.
• e-Ticaret marketplace sync: Trendyol/Hepsiburada/N11 webhook entegrasyonlarında stok ve sipariş sync için outbox + retry tasarımı şart.
• KVKK gereklilikleri: Webhook log’larında müşteri verisi 30-90 gün saklanmalı; sonrası purge/anonymize.
• Süresi geçen webhook denemeleri: 3,3 gün retry penceresi Türkiye için pratik — daha uzun spam riski.
• Müşteri destek yükü: Outbound webhook dashboard’unu müşteriye sunmak, “neden bana event gelmiyor” destek ticket’larını %60-70 azaltır.

Anti-Pattern ve Yaygın Hatalar

• Webhook handler’da business logic: Sender timeout’a düşürür. Queue + worker.
• İmza yok: Saldırgan webhook simüle edip sahte ödeme/iptal event’i gönderebilir.
• Idempotency yok: Çift ödeme, çift email — destek cehennemi.
• DLQ yok: Başarısız event’ler kayboluyor, kimse fark etmiyor.
• Müşteriye log gösterilmiyor: Müşteri “neden gelmedi” diyor; destek ticket’ları tıkanıyor.
• Rate limit yok: Müşteri sistemini DDoS’larsanız ekosistem güveni sarsılır.

Sık Sorulan Sorular

Ömer Önal’dan pratik not: Türkiye’de webhook tasarımı yapan ekiplere danışmanlık verdiğimde gördüğüm en yaygın “production yangını” tetikleyicisi, idempotency’siz handler. Stripe veya Iyzico tek bir ödeme için 3 webhook gönderdiğinde sistem 3 kez tahsilat işliyor, sonra müşteri destek 4 saat manuel düzeltme yapmak zorunda kalıyor. Pratik öneri: webhook handler’ın ilk kontrolü her zaman idempotency key check olmalı — Redis SET NX ile. İkinci pratik: gün 1’den dashboard ile gelin. Müşteriler “neden gelmedi” diye destek açmadan önce kendileri kontrol edebilsin; bu hem müşteri memnuniyetini hem operasyonu kurtarır. Üçüncü öneri: outbound webhook altyapısını kendi yazmak istiyorsanız önce ROI hesabı yapın — Svix’in maliyeti aylık 200-500 USD; 2-3 hafta dev maliyeti + sürekli bakım yükü genelde daha pahalı. Sizin sisteminizde webhook altyapısı kendi yazımı mı, Svix/Hookdeck mi, yoksa “endpoint açtık çalışıyor” tarzı çıplak mı?

Sonuç

Webhook altyapısı, SaaS ürünün entegrasyon kalitesinin doğrudan ölçüsü. Doğru tasarlanmış bir webhook sistemi (HMAC + idempotency + exponential backoff + DLQ + dashboard) güvenilirliği %99,99‘a çıkarır, müşteri destek yükünü %70 azaltır, entegrasyon onboarding’ini %40 hızlandırır. Svix ve Hookdeck gibi platformlar 0’dan yazmanın kısayolu. Tamamlayıcı içerikler: event-driven mimari, gRPC vs REST vs GraphQL, API gateway karşılaştırması ve performance testing. İletişim formundan projeniz için webhook mimari değerlendirme talep edebilirsiniz.

Dış otorite kaynaklar: Svix · Stripe Webhooks · Hookdeck · webhooks.fyi best practices