İmza algoritması
Payven her istekte iki header gönderir:X-Payven-Signature header’ı ile karşılaştırırsınız:
- Timestamp’in 5 dakika içinde olduğunu kontrol edin (replay koruması)
- Body’i string olarak (parse etmeden) HMAC-SHA256 ile imzalayın
- Sonucu sabit zamanlı (constant-time) karşılaştırma ile doğrulayın
Örnek implementasyonlar
Önemli detaylar
Body’i raw olarak okuyun. Express’te
express.raw({ type: "application/json" }), ASP.NET’te Request.EnableBuffering() + StreamReader. Framework’ün otomatik JSON parser’ını bypass edin veya parse’tan önce raw bytes’ı kaydedin.Timestamp toleransı 5 dakika (
±300 saniye). Daha gevşek tolerance replay attack riski yaratır.Sabit zamanlı karşılaştırma kullanın (
crypto.timingSafeEqual, hmac.compare_digest, CryptographicOperations.FixedTimeEquals, hash_equals). == ile karşılaştırma timing attack açığı yaratır.Secret’ı environment variable olarak saklayın, public repo’ya commit etmeyin.
Ham UTF-8 byte’larıyla imzalayın. Pretty-print, BOM, satır sonu farklılıkları imzayı kıracaktır.
Secret rotasyonu
Bir webhook subscription’ın secret’ını rotasyonu için:İmza bozuk geliyorsa
| Sorun | Çözüm |
|---|---|
| Body parse + re-stringify ediliyor | app.use(express.raw()) veya raw body capture middleware ekleyin |
| Timestamp drift > 5 dakika | Sunucu saatinizi NTP ile senkronize edin |
| Boşluk / satır sonu fark | Body’i Buffer veya bytes olarak saklayın, string dönüşümlerinde encoding belirtin (utf8) |
| Secret yanlış | Konsoldan whsec_ ile başlayan değeri tam olarak kopyaladığınızdan emin olun |
X-Payven-Signature boş | Reverse proxy header strip yapıyor olabilir — Nginx config’de proxy_pass_request_headers on |
X-Payven-Delivery-Id ile birlikte destek ekibimize yazın.