Webhook HMAC imza doğrulama
Bir webhook imzası tutmuyorsa nedenini bulmak için gövdeyi ve gizli anahtarı yapıştırın; HMAC'i tarayıcıda hesaplayıp gelen imzayla karşılaştırın. Gövde ve gizli anahtar hiçbir sunucuya gönderilmez: hesap tarayıcının kendi şifreleme işlevleriyle yapılır.
İmzalanan metin, alıcının aldığı baytlarla birebir aynı olmalı. Satır sonu, boşluk ve sondaki yeni satır sonucu değiştirir. Gövde: 0 bayt (UTF-8)
Sağlayıcının verdiği anahtar. whsec_ gibi önekler çoğunlukla anahtarın parçasıdır ya da önekten sonrası base64'tür; sağlayıcının belgesine bakın.
Başlıktaki değeri olduğu gibi yapıştırın; sha256=, v1= gibi önekler ve t=…,v1=… biçimi ayıklanır. Hex ve base64/base64url kabul edilir.
Gizli anahtar ve gövde cihazınızdan çıkmaz; hesap tarayıcıda yapılır, hiçbir şey saklanmaz. Yine de üretim anahtarlarınızı herhangi bir web sayfasına yapıştırmak yerine test anahtarı kullanmanızı öneririz.
Doğrulamada dikkat
- İmzayı her zaman alınan ham baytlar üzerinden doğrulayın. Çerçevenizin gövdeyi JSON'a çevirip yeniden metne dönüştürmesi anahtar sırasını, boşlukları ve kaçış karakterlerini değiştirebilir; ham gövdeyi o aşamadan önce yakalayın.
- Sunucuda imzaları == ile değil, sabit-zamanlı bir işlevle karşılaştırın (Node'da crypto.timingSafeEqual, Python'da hmac.compare_digest). Erken çıkan bir karşılaştırma, zamanlama farkından imzanın sızmasına yol açabilir. Bu sayfa da sabit-zamanlı karşılaştırır, ancak tarayıcıdaki sonuç bir güvenlik sınırı değildir.
- İmza tek başına tekrar saldırısını (replay) engellemez. Sağlayıcı bir zaman damgası gönderiyorsa onu imzaya dahil edin ve tolerans penceresi (ör. 5 dakika) dışındaki istekleri reddedin; olay kimliğini saklayıp tekrarları yok sayın.
- Gizli anahtarı kodda ya da günlükte saklamayın; ortam değişkeni ya da gizli yönetimi kullanın ve sızdığından şüphelenirseniz hemen yenileyin.
Bu araç yalnızca imza hesabını ve karşılaştırmasını gösterir; sağlayıcınızın imza şemasının (zaman damgası birleştirme, anahtar öneki, başlık adı) ayrıntılarını doğrulamaz. Üretim anahtarlarınızı bir web sayfasına yapıştırmaktan kaçının; test anahtarı kullanın.
Webhook alıcılarınızı güvenli, tekrar-dayanıklı ve izlenebilir kurmak ister misiniz? İmza doğrulama, yeniden deneme ve kuyruk tasarımını birlikte yapabiliriz.
Görüşme talep edin01
Nasıl kullanılır
A
Webhook'un ham gövdesini ve gizli anahtarı yapıştırın; anahtarın biçimini (metin, hex, base64) ve algoritmayı seçin.
B
Hesaplanan imzayı hex ve base64 olarak görün; başlıktaki imzayı yapıştırırsanız eşleşme anında gösterilir.
C
Eşleşmiyorsa nedenler listesine bakın: ham bayt farkı, anahtar biçimi ve algoritma en sık nedenlerdir.
02
Webhook imzası nasıl çalışır?
Webhook gönderen taraf, istek gövdesinden ve alıcıyla paylaştığı gizli anahtardan bir HMAC hesaplar ve bunu bir başlıkla (ör. X-Hub-Signature-256: sha256=…) gönderir. Alıcı aynı hesabı kendi gizli anahtarıyla yapar; sonuçlar eşitse istek anahtarı bilen taraftan gelmiştir ve gövde yolda değişmemiştir.
HMAC, bir özet işlevi (SHA-256, SHA-384, SHA-512) ve anahtardan oluşur; kimlik doğrulama ve bütünlük sağlar, gizlilik sağlamaz. Gövde şifrelenmez, yalnızca imzalanır.
03
Hesaplama ve doğrulama
Araç, anahtarı ve gövdeyi baytlara çevirir (metin UTF-8 olarak) ve tarayıcının WebCrypto işlevi crypto.subtle ile HMAC hesaplar. Sonuç hex (küçük harf) ve base64 olarak gösterilir. Hesap RFC 4231 test vektörleriyle sınanmıştır.
Gelen imza hex ya da base64/base64url olabilir; uzunluğu algoritmanın çıktısına uyan biçim seçilir. Karşılaştırma tüm baytlar üzerinden, ilk farkta durmadan yapılır.
04
Sağlayıcıya göre farklar
GitHub imzayı sha256=<hex> biçiminde gönderir ve ham gövdeyi imzalar. Stripe, t=<zaman>,v1=<hex> biçiminde gönderir ve zaman damgası ile gövdeyi 't.gövde' olarak birleştirip imzalar; bu durumda gövde kutusuna birleştirilmiş metni koyun. Bazı sağlayıcılar imzayı base64 verir, bazıları anahtarı base64 kodlu ister.
Emin olamadığınızda sağlayıcının belgesindeki örnek isteği ve beklenen imzayı bu araca girip hesabın tuttuğunu doğrulayın; ardından aynı adımları kodunuza taşıyın.
Sık sorulanlar
- Gizli anahtarım bir yere gönderiliyor mu?
- Hayır. Hesap tarayıcının yerleşik WebCrypto işleviyle sizin cihazınızda yapılır; ne anahtar ne gövde bir sunucuya gönderilir ya da saklanır. Buna rağmen canlı sistem anahtarlarını yapıştırmak yerine test anahtarı kullanmanızı öneririz.
- Neden imza tutmuyor? Gövdeyi birebir yapıştırdım.
- Metin kutusu satır sonlarını LF'ye çevirir ve görünmeyen karakterleri gizleyebilir. Gövde sağlayıcıda CRLF ile imzalandıysa satır sonu seçeneğinden CRLF'yi seçin. Sondaki yeni satırın ve JSON içindeki boşlukların da aynı olması gerekir. En güvenilir yol, sunucunuzda ham gövdeyi günlüğe yazıp buraya oradan kopyalamaktır.
- Anahtar base64 ise ne yapmalıyım?
- Anahtar biçimi olarak Base64'ü seçin; araç anahtarı önce baytlara çözer. Stripe gibi bazı sağlayıcılarda whsec_ önekinden sonraki kısım base64 kodlu anahtardır: öneki çıkarıp kalanı Base64 olarak girin. Önek dahil bütün metni anahtar saymak yanlış sonuç verir.
- Neden == yerine sabit-zamanlı karşılaştırma?
- == ya da === ilk farklı baytta durur; bu, yanıt süresinden imzanın baytlarını tahmin etmeye imkân verebilir. Sabit-zamanlı karşılaştırma bütün baytlara aynı süreyi harcar. Sunucuda crypto.timingSafeEqual (Node) ya da hmac.compare_digest (Python) kullanın; iki girdinin uzunluğu eşit olmalıdır.
- HMAC-SHA256 yerine hangisini seçmeliyim?
- Sağlayıcınızın belgesindekini. Pratikte neredeyse tüm webhook'lar SHA-256 kullanır; SHA-384 ve SHA-512 daha uzun çıktı verir ve bazı sağlayıcılarda bulunur. Yeni bir sistem tasarlıyorsanız HMAC-SHA256 yeterlidir. SHA-1 tabanlı eski imzalar bu araçta yoktur.
Webhook entegrasyonlarınızı güvenli kuralım
CRM, ERP, ödeme ve lojistik sistemleri arasındaki webhook alıcılarını imza doğrulama, tekrar koruması ve yeniden deneme ile birlikte tasarlıyoruz. Ücretsiz keşif görüşmesinde mevcut akışınızı konuşalım.