Ödeme Sistemlerinde Webhook Güvenilirliği (Odeme Sistemlerinde Webhook Guvenilirligi)

Webhook, garantili bir mesaj değildir

PSP'nin size gönderdiği webhook, “bu olay tam olarak bir kez ve doğru sırada gelecek” garantisi taşımaz. Aksine dört farklı şekilde bozulabilir: aynı olay birden fazla kez gelebilir, bir olay hiç gelmeyebilir, olaylar gönderildiği sıradan farklı bir sırada ulaşabilir, ve bir olay dakikalar sonra gecikmeli gelebilir.

PSP → Webhook
  ⚠ Duplicate: aynı olay iki kez
  ⚠ Missing: olay hiç gelmez
  ⚠ Out-of-order: capture bildirimi, authorize bildiriminden önce gelir
  ⚠ Delayed: olay dakikalar sonra ulaşır

Bu bölüm, webhook handler'ınızı bu dört senaryoya karşı nasıl dayanıklı hale getireceğinizi anlatıyor.

Kavramlar ilk geçtiği yerde

📦 Webhook
Bir dış sistemin (PSP), kendi tarafında gerçekleşen bir olayı bildirmek için sizin uç noktanıza yaptığı HTTP çağrısı.

📦 Signature Verification
Gelen webhook'un gerçekten PSP'den geldiğini, içeriğin değiştirilmediğini doğrulayan kriptografik kontrol.

📦 At-least-once Delivery
Bir olayın en az bir kez, bazen daha fazla kez teslim edileceğini garanti eden; ama sıra veya tekrar sayısı garantisi vermeyen teslimat modeli.

📦 ACK (Acknowledgement)
Webhook alıcısının, olayı aldığını PSP'ye bildiren hızlı HTTP cevabı (genellikle 200).

📦 Durable Write
İşlemin sonucu ne olursa olsun, olayın kalıcı depoya yazılmış olması; bellek içinde kalan bir kayıt değildir.

Bu kavramların hepsi tek bir kurala hizmet eder: webhook handler'ınız, gelen olayı ne olursa olsun önce güvenle kaydetmeli, ağır işi ancak ondan sonra yapmalıdır.

Duplicate: aynı olay iki kez gelir

PSP, sizden zamanında 200 cevabı alamazsa (ağ sorunu, sunucu yavaşlığı), aynı olayı tekrar gönderir. Bu davranış bir hata değil, PSP'nin at-least-once garantisinin doğal sonucudur. Beşinci bölümde detaylandırdığımız event id + inbox deseni burada birinci savunma hattıdır.

Webhook #1: evt_001 → işlenir
Webhook #2: evt_001 (tekrar) → inbox'ta zaten var, işlem atlanır, 200 döner

Missing: olay hiç gelmez

Bazen webhook hiç ulaşmaz: ağ kesintisi, PSP tarafında bir hata veya sizin uç noktanızın geçici olarak erişilemez olması. Sadece webhook'a güvenen bir sistem, bu durumda sonsuza dek “bilmiyorum” durumunda kalır. Bu yüzden webhook, tek gerçek kaynağı değil, birincil bildirim kanalı olmalıdır; PSP'nin durum sorgulama API'siyle periyodik bir reconciliation (uzlaştırma) her zaman ikincil bir güvenlik ağı olarak durmalıdır.

Webhook (birincil, hızlı)
  + Periyodik durum sorgusu (ikincil, yavaş ama garantili)
  = webhook kaybolsa bile gerçek er ya da geç yakalanır

Out-of-order: olaylar sırasız gelir

Ağ katmanı, olayların gönderildiği sırayla ulaşmasını garanti etmez. Örneğin bir “capture” bildirimi, ondan önce gelmesi beklenen bir “authorize” bildiriminden önce ulaşabilir. Handler'ınız, olayın taşıdığı zaman damgasını veya sürüm numarasını kontrol etmeden state machine'i güncellerse, ikinci bölümde tanımladığımız guard'lar burada devreye girmelidir.

Gelen: payment.captured (t=2)
Gelen: payment.authorized (t=1, ama sonra ulaştı)
  → guard: t=1 olayı, zaten t=2'ye ulaşmış bir state'i geriye alamaz, sessizce reddedilir

Delayed: olay gecikmeli gelir

Bir webhook, PSP tarafındaki kuyruklama veya sizin tarafınızdaki işlem gecikmesi nedeniyle dakikalar sonra ulaşabilir. Bu durumda handler'ınızın “şu an” ile olayın “gerçekleştiği an” arasındaki farkı ayırt etmesi gerekir; iş kararları olayın kendi zaman damgasına göre değil, işlendiği ana göre alınırsa, sıralama hataları büyür.

Neden ağır işi senkron çalıştırmamalısınız

Webhook handler'ınızda imza doğrulama, minimal doğrulama ve durable write (inbox'a yazma) dışında hiçbir ağır iş yapılmamalıdır. Stok düşme, finans kaydı, bildirim gönderme gibi adımlar ayrı bir arka plan job'ına devredilmelidir.

Webhook Handler (hızlı, senkron)
  1. İmzayı doğrula
  2. Minimal şema kontrolü yap
  3. Olayı inbox'a yaz (durable)
  4. 200 OK döndür

Arka plan Job (yavaş, asenkron)
  5. İnbox'taki olayı oku
  6. Gerçek iş kararlarını uygula (stok, finans, bildirim)

Bu ayrım iki nedenden kritiktir: Birincisi, PSP genellikle webhook cevabı için kısa bir zaman aşımı uygular (birkaç saniye); ağır iş bu süreyi aşarsa PSP isteği başarısız sayıp tekrar gönderir, bu da duplicate sayısını artırır. İkincisi, ağır işin senkron çalışması, webhook handler'ınızı dış sistemin performansına (stok servisi yavaşsa) bağımlı kılar; bu bağımlılık, webhook'un kendisinin de zaman aşımına uğramasına yol açabilir.

Bu bölümde en çok karışan eşleştirmeler

❌ Webhook, tek ve güvenilir gerçek kaynağıdır
✓ Webhook birincil bildirim kanalıdır; periyodik durum sorgusu ikincil güvenlik ağıdır

❌ 200 dönmek, işin tamamlandığı anlamına gelir
✓ 200, olayın güvenle alındığı anlamına gelir; işin tamamlanması ayrı bir asenkron adımdır

❌ Webhook'lar her zaman gönderildiği sırayla ulaşır
✓ Sıralama garanti edilmez; guard'lar olmadan state machine geriye kayabilir

❌ İmza doğrulaması opsiyoneldir, IP allowlist yeterlidir
✓ İmza doğrulaması, sahte veya değiştirilmiş webhook'lara karşı asıl savunmadır

Webhook handler'ınızı denetleme listesi

1. Webhook handler'ınız imza doğrulamasını her istekte yapıyor mu, yoksa sadece IP allowlist'e mi güveniyor?
2. Handler, olayı inbox'a yazmadan önce hangi ağır işleri senkron çalıştırıyor?
3. Webhook hiç gelmezse, sisteminiz bunu kaç saat/gün içinde fark ediyor? Bir reconciliation job'ınız var mı?
4. Sırasız gelen iki webhook, state machine'inizi geçersiz bir duruma sokabilir mi? Guard'larınızı test ettiniz mi?
5. PSP'nin webhook zaman aşımı süresi nedir ve handler'ınız bu sürenin ne kadarını kullanıyor?

Bu beş sorudan birine “hayır, kontrol etmedik” diyorsanız, webhook güvenilirliğiniz muhtemelen test edilmemiş bir varsayıma dayanıyor.

Bu bölümden aklında kalması gerekenler

1. Webhook'lar duplicate, missing, out-of-order ve delayed olabilir; handler'ınız bu dördünü de varsayım olarak almalıdır.
2. İmza doğrulaması, sahte webhook'lara karşı asıl savunma hattıdır; IP allowlist yeterli değildir.
3. Handler hızlı ACK vermeli, ağır işi asenkron bir job'a devretmelidir; senkron ağır iş, hem timeout hem duplicate riskini büyütür.
4. Webhook birincil kanaldır ama tek gerçek kaynağı değildir; periyodik durum sorgusu her zaman ikincil bir güvenlik ağı olmalıdır.

Webhook'a “gelecek” diye güvenmek bir tasarım değildir; “gelmeyebilir, tekrar gelebilir, sırasız gelebilir” diye tasarlamak tasarımdır.