İçeriğe geç

Webhook İmza Doğrulama ve Replay Koruması Nasıl Kurulur

Seri Çevresel Arabirim
Webhook İmza Doğrulama ve Replay Koruması Nasıl Kurulur

Webhook imza doğrulaması, gelen bir bildirimin gerçekten beklenen kaynaktan geldiğini kanıtlayan bir kontrol yöntemidir; gönderen taraf, mesajı gizli bir anahtarla imzalar ve alan taraf aynı anahtarla imzayı yeniden hesaplayıp karşılaştırır. Replay (tekrar oynatma) koruması ise aynı bildirimin ikinci kez işlenmesini önler.

İmza Doğrulaması Neden Gerekli?

Bir webhook adresi (URL) genellikle herkese açıktır; adresi bilen biri, sahte bir bildirim gönderip sistemi yanıltmaya çalışabilir. İmza doğrulaması olmadan sistem, gelen her isteği gerçek sayar. İmza doğrulamasıyla, yalnızca doğru gizli anahtarla imzalanmış istekler işleme alınır; anahtarı bilmeyen biri geçerli bir imza üretemez.

Bu kontrol özellikle sipariş, ödeme veya stok güncellemesi gibi webhook bildirimlerinde kritik hâle gelir; çünkü bu bildirimler doğrudan bir iş akışını (örneğin bir siparişin "ödendi" olarak işaretlenmesini) tetikler. Sahte bir bildirim doğrulama olmadan kabul edilirse, gerçekte ödenmemiş bir sipariş ödenmiş gibi işlenebilir.

İmza Doğrulaması Teknik Olarak Nasıl Çalışır?

Gönderen taraf, isteğin gövdesini (ve genellikle bir zaman damgasını) gizli bir anahtarla birlikte bir özet fonksiyonundan geçirir ve sonucu bir başlık alanında (örneğin bir imza başlığı) gönderir. Alan sistem, aynı gövdeyi aynı anahtarla kendi tarafında yeniden hesaplar; iki sonuç eşleşmiyorsa istek reddedilir. Bu hesaplama, isteğin içeriği yolda değiştirilmişse de farklı bir sonuç üreteceğinden, hem kaynağı hem de bütünlüğü doğrular.

Gizli anahtarın kendisi, yazılımın kodunda açıkça yazılı tutulmamalı, ayrı bir yapılandırma veya anahtar saklama mekanizmasında saklanmalıdır. Anahtar bir şekilde başkasının eline geçerse, o kişi geçerli imzalar üretebilir hâle gelir; bu durumda yapılacak tek şey anahtarı yenilemek ve karşı tarafla (bildirim gönderen sistemle) yeni anahtarı paylaşmaktır.

AdımNe kontrol edilir
İmza hesaplamaGövde + gizli anahtar ile yeniden hesaplanan imza, gelen imzayla eşleşiyor mu
Zaman damgası kontrolüİstek belirli bir süre içinde mi geldi, çok eski mi
Tekil kimlik kontrolüBu bildirim kimliği önceden işlendi mi

Replay Koruması Olmadan Ne Risk Oluşur?

İmza doğru olsa bile, aynı istek bir ağ kaydından yakalanıp tekrar gönderilebilir; imza geçerli olduğu için sistem bunu da gerçek sanabilir. Bu senaryoya karşı iki yaygın önlem birlikte kullanılır: isteğe eklenen zaman damgasının belirli bir süreyi (örneğin birkaç dakikayı) aşmaması kuralı ve her bildirimin kendine özgü bir kimliğinin daha önce işlenip işlenmediğinin kontrol edilmesi. İkinci kez gelen aynı kimlikteki bildirim, ikinci kez işlenmez, sadece "zaten alındı" olarak işaretlenir.

Bu kontrolün çalışması için işlenen bildirim kimliklerinin bir süre (örneğin zaman damgası sınırıyla uyumlu bir pencere boyunca) saklanması gerekir; sonsuza kadar saklamak gerekmez, çünkü zaman damgası kontrolü zaten çok eski bir isteği reddedecektir. Bu iki kontrolün (zaman damgası ve tekil kimlik) birlikte çalışması, tek başına birinin bırakacağı boşluğu kapatır.

Bu Kontroller Hangi Noktada Yapılmalı?

Doğrulama, bildirim iş mantığına (örneğin sipariş güncellemesi) ulaşmadan en başta yapılmalıdır; imza geçersizse istek hemen reddedilir, hiçbir veri işlenmez. Zaman damgası ve tekil kimlik kontrolü de aynı ilk aşamada yapılır. Bu sıralama, geçersiz veya tekrarlanan bir isteğin sistemin derinine inmesini önler.

Reddedilen isteklerin bir kaydının (hangi sebeple reddedildiği ile birlikte) tutulması da faydalıdır; bu kayıt, gerçek bir saldırı denemesi mi yoksa gönderen tarafta bir yapılandırma hatası mı olduğunu ayırt etmeye yardımcı olur. Sürekli aynı kaynaktan gelen başarısız imza denemeleri, karşı tarafla iletişime geçilmesi gereken bir yapılandırma sorununa işaret edebilir.

Karşı Taraf Anahtarı Değiştirirse Ne Olur?

Gizli anahtar, zaman zaman güvenlik gerekçesiyle yenilenebilir; bu durumda gönderen taraf yeni anahtarla imzalamaya başlar ama alan sistem hâlâ eski anahtarla doğrulama yapıyorsa, tüm gelen istekler geçersiz imza hatasıyla reddedilmeye başlar. Bu riski azaltmak için anahtar değişikliği öncesinde karşı tarafla bir geçiş penceresi (eski ve yeni anahtarın bir süre birlikte kabul edildiği bir dönem) konuşulması, kesintisiz bir geçiş sağlar.

Webhook Ulaşmazsa veya Gecikirse Ne Olur?

Ağ sorunları nedeniyle bir webhook isteği hiç ulaşmayabilir veya gecikebilir; bu durumda sistem yalnızca gelen bildirime güvenirse, karşılığı gelmeyen bir olay fark edilmeden kalır. Bu riske karşı, kritik bildirimler için karşı tarafın "yeniden deneme" (retry) mekanizmasına ek olarak, alan sistemin de belirli aralıklarla durumu kendisi sorguladığı bir yedek kontrol (örneğin günde bir kez durum senkronizasyonu) kurulması, webhook'un tek başına güvenilir tek kaynak olmasının getirdiği riski azaltır.

Kısa Kontrol Listesi

  • Her webhook isteğinin imzasını gizli anahtarla yeniden hesaplayıp doğrulayın.
  • İsteğin zaman damgasının güncel olup olmadığını kontrol edin.
  • Her bildirimin tekil kimliğini, önceden işlenip işlenmediğini kontrol etmek için saklayın.
  • Doğrulama başarısızsa isteği iş mantığına ulaştırmadan reddedin.
  • Anahtar değişikliklerini karşı tarafla önceden koordine edin.

KAV Yazılım, entegrasyon projelerinde webhook güvenliğinin imza doğrulama ve tekrar oynatma koruması ile kurulmasında destek verir.

Sık sorulan sorular

Webhook URL'si gizli tutulursa imza doğrulamaya gerek kalır mı?

Evet, URL'nin gizli kalacağı garanti edilemez; imza doğrulaması her durumda ek bir güvenlik katmanıdır.

İmza doğrulaması istek içeriğinin değişmediğini de garanti eder mi?

Evet, imza gövdeden hesaplandığı için içerik değişirse hesaplanan imza da farklı çıkar ve doğrulama başarısız olur.

Replay koruması olmadan yalnızca imza yeterli mi?

Hayır, geçerli bir imzalı istek yakalanıp tekrar gönderilebilir; bu yüzden zaman damgası ve tekil kimlik kontrolü de gerekir.

Doğrulama hangi aşamada yapılmalı?

İstek iş mantığına ulaşmadan en başta yapılmalı; geçersiz istek hiçbir veri işlemeden reddedilmelidir.
  • entegrasyon
  • güvenlik
  • iş akışı
  • veri güvenliği