Stripe Webhook Güvenliği ve En İyi Uygulamalar

Stripe Webhook Güvenliği: Kritik Kontrol Noktaları

Stripe webhook'ları, ödeme işlemlerini gerçek zamanlı olarak uygulamanıza bildirir. Müşteri ödeme yaptığında, abonelik iptal ettiğinde veya ücret geri yüklendiğinde, Stripe bu olayları webhook aracılığıyla sizin sunucunuza gönderir. Ancak bu veri akışının güvenliği, sistem bütünlüğünüzün temelini oluşturur. İmzasız veya doğrulanmamış webhook'lar, sahte işlemler, veri manipülasyonu ve maliyetli hataların kapısını açabilir.

Stripe webhook güvenliğini sağlamak üç temel ilkeye dayanır: yetki doğrulaması, imza doğrulama ve yapılandırma yönetimi. Bu rehberde, her birini detaylı olarak inceleyerek, üretim ortamında yapılması gereken adımları analiz edeceğiz.

1. Webhook İmzasını Doğrulama Mekanizması

Stripe webhook'larının güvenliğinin en kritik aşaması, imza doğrulamasıdır. Stripe, her webhook göndermeden önce, özel bir anahtarını (webhook signing secret) kullanarak isteği imzalar. Bu imza, HTTP başlığında Stripe-Signature alanında yer alır. İmza doğrulanmadığında, kötü niyetli bir aktörün sahte webhook gönderebilmesi olasıdır.

İmza doğrulamasının temel adımları:

Stripe Dashboard'dan webhook signing secret'i güvenli bir yerde sakla (ortam değişkeni kullan)
Gelen isteğin raw body'sini ve signing secret'i kullanarak hash değeri hesapla
Hesaplanan hash ile Stripe-Signature başlığındaki değeri karşılaştır
Eğer hash eşleşmezse, webhook'u kabul etme ve 400 durum kodu döndür

İmza doğrulaması, webhook işlendikten sonra değil, hemen ilk adımda yapılmalıdır. Bu, gereksiz işlem yükü ve potansiyel veri kayıplarını önler. Stripe, bu doğrulama için resmi SDK'lar sağlar ve bu SDK'ların kullanılması güvenlik açıkları riskini minimize eder.

2. Event Timestamp Kontrolü ve Replay Saldırıları

İmza doğrulandıktan sonraki adım, webhook'un zamanının kontrol edilmesidir. Stripe, Stripe-Signature başlığında bir t parametresi içerir; bu, webhook'un gönderilme zamanını UNIX timestamp olarak gösterir. Eski webhook'lar tekrar gönderilen (replay) saldırılar aracılığıyla sistemi manipüle etmek için kullanılabilir.

Zaman kontrolü yapılırken:

Webhook timestamp'ı ile geçerli zamanı karşılaştır
Belirli bir pencere (örneğin 5 dakika) dışında kalan webhook'ları reddet
Her webhook'un event ID'sini veritabanında sakla ve tekrar işlenmesini önle

Event ID depolaması, idempotency sağlar. Ağ sorunları nedeniyle Stripe aynı webhook'u birden fazla kez gönderebilir; bu durumda, depolanmış event ID'leri kontrol ederek gereksiz tekrar işlemeleri engellersiniz.

3. Üretim Ortamında Hata Yönetimi ve Loglama

Webhook işlenmesi sırasında oluşabilecek hatalar, ödeme sisteminin güvenilirliğini doğrudan etkiler. Geliştirme ortamında test ettiğiniz bir webhook işlemi, üretimde farklı davranabilir.

Üretim ortamında uygulanması gereken uygulamalar:

Webhook işlemesinde oluşan tüm hataları ayrıntılı olarak logla (tarih, event ID, hata türü, stack trace)
İşleme başarısız olursa, webhook'u sırada tut ve belirli bir gecikmeyle yeniden dene
Kritik hatalar için (örneğin veritabanı bağlantısı kapalı) uyarı sistemi kur
200 HTTP durum kodunu yalnızca webhook tamamen başarıyla işlendikten sonra döndür

Webhook işlemesi sırasında timeout oluşması oldukça yaygındır. Bu durumda, işlemi hemen tamamlamak yerine, webhook isteğine 200 dönerek Stripe'a "aldım" mesajı verin, ardından işlemi arka planda sırada bekletip ileriki bir zamanda işleyin.

4. Endpoint Yapılandırması ve İzin Verilen Event Türleri

Stripe Dashboard'da webhook endpoint kurulumu sırasında, hangi event türlerini almak istediğinizi seçebilirsiniz. Güvenlik açısından, yalnızca ihtiyaç duyduğunuz event'leri aktifleştir. Gereksiz event'ler işleme alınırsa, yüksek trafikli ve karmaşık sistemlerde performans düşüşü ve loglama karmaşıklığı artabilir.

Yapılandırma kontrol listesi:

Endpoint URL'ini HTTPS kullan (hiçbir zaman HTTP değil)
Webhook signing secret'i ortam değişkeni olarak sakla, asla hardcode etme
Düzenli aralıklarla endpoint'in çalışıp çalışmadığını test et
Endpoint IP adresine dayanmayan bir yöntem kullan; Stripe'ın IP adresleri değişebilir

Stripe, webhook'ları 3 gün boyunca yeniden göndermeye çalışır. Bu dönem içinde endpoint'iniz müsait olmazsa, işlemler kaydedilmez. İzleme (monitoring) ve hata yönetimi bu nedenle çok önemlidir.

5. Geliştirme vs. Üretim Ortamı Ayrımı

Stripe test ve canlı API anahtarlarını ayrı tutarak, geliştirme sırasında gerçek verileri etkilenmekten korur. Webhook signing secret'leri de bu ayrımı takip etmelidir: geliştirme ortamında test signing secret'ini, üretimde gerçek signing secret'ini kullan. Ortamları karıştırmak, veri tutarsızlığı ve güvenlik açıklarına yol açar.

Pratik İpucu: Yerel geliştirmede webhook'ları test etmek için Stripe CLI kullanabilirsiniz. Bu araç, Stripe'ın webhook'larını doğrudan terminalde simüle eder ve kendi local sunucunuzu bu webhook'larla test etmek için bir tunnel sağlar.

Sonuç: Derinlemesine Kontrol ve Düzenli Gözden Geçirme

Stripe webhook güvenliği, tek bir teknik uygulamaya indirgenemez. İmza doğrulaması, zaman kontrolü, idempotency, hata yönetimi ve ortam ayrımının kombinasyonu, bütünlüklü bir savunma stratejisine dönüşür. Ödeme verileriniz oldukça değerlidir; webhook işlemesinde eksik adım bırakmak, büyük risklere açılmak anlamına gelir. Sistem kurulduktan sonra, düzenli olarak logging kayıtlarını inceleyip, hata oranlarını takip ederek, webhook işlemesinin sağlıklı çalışıp çalışmadığını doğrulayın.