Skip to main content
Payven her webhook isteğinde HMAC-SHA256 imza gönderir. Bu imza, isteğin gerçekten Payven’den geldiğini ve request body’sinin değiştirilmediğini garanti eder. Public webhook endpoint’inizi açıyorsanız imza doğrulama zorunludur.

İmza algoritması

Payven her istekte iki header gönderir:
İmza şu formülle üretilir:
Sizin tarafınızda bu üç adımı uygulayıp X-Payven-Signature header’ı ile karşılaştırırsınız:
  1. Timestamp’in 5 dakika içinde olduğunu kontrol edin (replay koruması)
  2. Body’i string olarak (parse etmeden) HMAC-SHA256 ile imzalayın
  3. Sonucu sabit zamanlı (constant-time) karşılaştırma ile doğrulayın
Body’i parse etmeden imzalayın. JSON.parse() + JSON.stringify() döngüsü property sırasını değiştirip imzayı bozar. Raw string’i mutlaka middleware’den önce okuyun.

Ö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:
Yanıt yeni secret’ı döner. Eski secret 24 saat boyunca geçerli kalır — bu sürede her iki secret ile imzalanmış istekler kabul edilir, böylece zero-downtime geçiş yaparsınız:

İmza bozuk geliyorsa

Hâlâ çözemediğiniz durumda X-Payven-Delivery-Id ile birlikte destek ekibimize yazın.