Webhook Alıcısı Kurmak: Dış Servisten Gelen Bildirimleri İşlemek

Ödeme sağlayıcınız "ödeme başarılı" bildirimini sitenize gönderiyor. Siz de o bildirimi alıp siparişi onaylıyorsunuz. Ta ki biri o adrese kendi uydurduğu bir bildirim gönderene kadar.

Bu yazı, hosting hesabınızda güvenli bir webhook alıcısı kurmayı ele alıyor.

Webhook Nedir?

Klasik yaklaşımın tersine çalışır:

Avantaj hem hız hem kaynak tasarrufudur: durum değişikliğini saniyeler içinde öğrenirsiniz ve boşa giden binlerce sorgu isteği yapmazsınız.

Dezavantajı ise sorumluluktur. Artık sitenizde, internete açık ve dış dünyanın veri gönderdiği bir uç nokta vardır.

İlk Kural: Doğrulama

Gelen her isteğe güvenilemez:

1. İmza doğrulaması yapın.
2. Gönderen adresi kontrol edin.
3. Zaman damgasını kontrol edin.
4. Bilgiyi kaynaktan teyit edin.

Birinci madde temel korumadır: servis sağlayıcı, gövdeyi paylaşılan bir gizli anahtarla imzalar ve siz aynı hesaplamayı yaparak imzanın uyup uymadığını kontrol edersiniz — uymuyorsa istek sahtedir.

İmza doğrulamasını atlayan bir alıcı, herkesin sipariş onaylayabildiği bir kapıdır.

Dördüncü madde ise en güçlü korumadır ve ödeme gibi kritik akışlarda mutlaka yapılmalıdır: bildirimi bir tetikleyici olarak kabul edip, gerçek durumu servis sağlayıcının API'sinden yeniden sorgulamak, sahte bildirim riskini tamamen ortadan kaldırır.

Üçüncü madde ise tekrar saldırılarını engeller. Eski ve geçerli bir bildirim yeniden gönderilirse zaman damgası bunu ele verir.

Aynı Bildirim İki Kez Gelirse

Bu istisna değil, kuraldır:

• Ağ sorunları tekrar gönderime yol açar.
• Yanıtınız geç ulaşırsa yeniden denenir.
• Bazı servisler garanti için birden fazla gönderir.

Sonuç, işlemenizin tekrara dayanıklı olması gerektiğidir: aynı ödeme bildirimini iki kez işlerseniz müşteriye iki kez ürün gönderirsiniz veya bakiyesini iki kez artırırsınız.

Çözüm basittir: her bildirimin bir kimliği vardır. Bu kimliği kaydedin ve daha önce işlenmiş bir kimlik geldiğinde işlemi atlayıp başarı yanıtı dönün.

Bu kayıt, veritabanında benzersiz bir sütunla tutulmalıdır. Böylece eşzamanlı iki bildirim bile ikinci kez işlenemez.

Hızlı Yanıt Vermek

Servis sağlayıcılar yanıtınızı beklemez:

İkinci satır sık yapılan bir tasarım hatasıdır: bildirimi alıp e-posta gönderme, fatura üretme ve stok güncelleme gibi işleri aynı istek içinde yaparsanız, süre aşılır ve servis bildirimi başarısız sayıp tekrar gönderir.

Doğru desen şudur: bildirimi kaydet, hemen başarı yanıtı dön, asıl işi arka planda yap.

Üçüncü satır ise bilinçli kullanılabilir. Gerçekten işleyemediyseniz hata dönmek, servisin tekrar denemesini sağlar.

Uç Nokta Adresi

Alıcı adresinin kendisi de bir karardır:

• Tahmin edilmesi zor bir yol seçin.
• Şifreli bağlantı zorunlu olsun.
• Yalnızca POST kabul edin.
• Her servis için ayrı adres kullanın.

Dördüncü madde teşhis ve güvenliği birlikte iyileştirir: tüm servisleri tek bir adrese toplamak, hangi servisin ne gönderdiğini ayırmayı zorlaştırır ve bir servisin gizli anahtarı sızdığında hepsini etkiler.

Birinci madde ise tek başına güvenlik değildir ama otomatik tarama trafiğini azaltır.

İkinci madde zorunludur. Şifresiz gönderilen bir bildirim, yolda okunabilir ve değiştirilebilir.

Kayıt Tutmak

Webhook sorunlarının teşhisi kayıt olmadan imkânsızdır:

1. Gelen ham gövdeyi kaydedin.
2. Başlıkları kaydedin.
3. İmza doğrulama sonucunu yazın.
4. İşleme sonucunu yazın.
5. Saklama süresi belirleyin.

Birinci madde çok değerlidir çünkü sorunlar genellikle beklenmedik veri biçiminden kaynaklanır: servis sağlayıcı gövde yapısını değiştirdiğinde, kaydettiğiniz ham veri olmadan neyin değiştiğini asla anlayamazsınız.

Beşinci madde ise iki nedenle gereklidir. Hem disk dolmasın hem de içinde kişisel veri barındıran kayıtlar süresiz saklanmasın.

Üçüncü madde saldırı tespitine yardımcı olur. Doğrulamayı geçemeyen isteklerin sayısındaki artış, birinin denediğini gösterir.

Geliştirme ve Test

Dördüncü satır atlanmaması gereken bir testtir: kendi uç noktanıza imzasız bir istek gönderip reddedildiğini görmek, doğrulamanın gerçekten çalıştığının tek kanıtıdır.

Bu test yapılmadığında, doğrulama kodunun bir hata nedeniyle her isteği kabul ettiği fark edilmez.

Üçüncü satır ise tekrar dayanıklılığını doğrular ve gerçek bir çift işleme kazasını önler.

Uç noktanızın dışarıdan erişilebilir ve şifreli olması gerekir; hosting paketleri içinde sunulan ücretsiz SSL sertifikası bu gereksinimi karşılar.

Sonuç

Webhook alıcısı kurarken iki şey pazarlık konusu değildir. Birincisi imza doğrulamasıdır — onsuz bir alıcı, herkesin sipariş onaylayabildiği bir kapıdır. Ödeme gibi kritik akışlarda bir adım daha atın: bildirimi tetikleyici sayıp gerçek durumu sağlayıcının API'sinden yeniden sorgulayın. İkincisi tekrar dayanıklılığıdır: aynı bildirim iki kez gelirse müşteriye iki kez ürün gönderirsiniz — bildirim kimliğini benzersiz bir sütunda tutun ve hemen başarı yanıtı dönüp asıl işi arka planda yapın.

Sıkça Sorulan Sorular (SSS)

Gelen bildirimin gerçek olduğunu nasıl anlarım?

İmza doğrulamasıyla: sağlayıcı gövdeyi paylaşılan gizli anahtarla imzalar, siz aynı hesabı yapıp karşılaştırırsınız. Ödeme gibi kritik akışlarda bir adım daha atın — bildirimi yalnızca tetikleyici sayıp gerçek durumu sağlayıcının API'sinden yeniden sorgulayın.

Aynı bildirim iki kez gelirse ne olur?

Bu istisna değil kuraldır; ağ sorunları ve geciken yanıtlar tekrar gönderime yol açar. Önlem almazsanız müşteriye iki kez ürün gönderirsiniz. Her bildirimin kimliğini veritabanında benzersiz bir sütunda saklayın ve daha önce işlenmiş kimlik gelirse işlemi atlayıp başarı yanıtı dönün.

Ne kadar sürede yanıt vermeliyim?

Hemen. Bildirimi kaydedip anında başarı dönün, asıl işi arka planda yapın. E-posta gönderme, fatura üretme ve stok güncellemeyi aynı istek içinde yaparsanız süre aşılır, servis bildirimi başarısız sayar ve tekrar gönderir.

Doğrulamanın çalıştığını nasıl test ederim?

Kendi uç noktanıza imzasız bir istek gönderip reddedildiğini görerek. Bu, doğrulamanın gerçekten çalıştığının tek kanıtıdır — yapılmadığında, kodun bir hata nedeniyle her isteği kabul ettiği fark edilmez. Ayrıca aynı bildirimi iki kez göndererek tekrar dayanıklılığını da test edin.