Kripto ödeme webhook güvenliği: imzalar, replay ve yeniden denemeler

Suawave webhook’larını RSA-SHA256, özgün baytlar, sipariş eşleştirme, kalıcı idempotency ve doğru alındı yanıtıyla güvenli işleyin.

Yayın tarihi , güncelleme

Düzenli bir masadaki dizüstü bilgisayar, asma kilit ve kablo güvenli webhook doğrulamasını temsil ediyor

Webhook güvenliği, isteğe güvenmeden imzayı doğrulamak, ödemeyi saklanan siparişle eşleştirmek ve etkilerini yalnızca bir kez kaydetmektir. Suawave’de x-ca-signature değerini RSA-SHA256 ile doğrulayın, imzalanan baytları koruyun ve UUID tekrarlarını kalıcı olarak eleyin. Yalnızca olay kalıcı işlemeye alındıktan sonra HTTP 200 ve *ok* döndürün.

İşleyici gerçek istek iki kez geldiğinde, iki ödeme aynı anda ulaştığında ve commit sonrasında süreç durduğunda doğru davranmalıdır. İmza kontrolü bu işin yalnızca bir parçasıdır.

1. Doğrulamadan önce baytları koruyun

Genel callback imzası base64 RSA-SHA256 ve PKCS#1 v1.5 kullanır. HTTPS üzerinden GET /pubkey/ ile PKIX PUBLIC KEY PEM alın. En az 2048 bit RSA isteyin ve önbelleğe koyun. HMAC sırrına veya özel imzalama anahtarına gerek yoktur.

Taşıma İmzalanan mesaj Sık hata
Varsayılan GET Özgün sorgulu tam dış URL Parametreleri sıralamak veya yeniden kodlamak
post=1 ile POST Tam ham gövde Formu yeniden kurmak
json=1 ile JSON POST Tam ham gövde Ayrıştırılmış JSON’u yeniden üretmek

json=1 önceliklidir. İlk create ticker/callback seçeneklerini sabitler; tekrarlanan çağrı mevcut siparişi yeniden yapılandırmaz.

Proxy arkasında yapılandırılmış güvenilir dış origin ile özgün kodlanmış istek hedefini birleştirin. İstekten gelen Host veya yönlendirme başlıklarına güvenmeyin. POST’u middleware’den önce yakalayın. İmza dokümantasyonuna bakın.

Kısa Node.js doğrulayıcısı

Bu işlev dokümantasyondaki JavaScript örneğidir, tam HTTP işleyicisi değildir. Anahtarı ayrı yükleyip doğrulayın; özgün hedefi ve değişmemiş POST gövdesini Buffer olarak geçirin.

const crypto = require('crypto');

function verifyCallback({ method, requestUri, rawBody, signature }, publicKeyPem, trustedOrigin) {
  let signed;
  if (method === 'GET') {
    signed = Buffer.from(trustedOrigin + requestUri, 'utf8');
  } else if (method === 'POST') {
    if (!Buffer.isBuffer(rawBody) || rawBody.length > 65536) return false;
    signed = rawBody;
  } else {
    return false;
  }
  if (!signature || !/^[A-Za-z0-9+/]+={0,2}$/.test(signature)) return false;
  const verifier = crypto.createVerify('RSA-SHA256');
  verifier.update(signed);
  return verifier.verify(publicKeyPem, signature, 'base64');
}

module.exports = { verifyCallback };

Express’te req.originalUrl kullanın ve POST’u ayrıştırmadan önce express.raw ile alın. HTTP sınırında da boyut limiti uygulayın. Anahtar ve doğrulama hataları HTTP 401 üretmeli, siparişi değiştirmemelidir. Diğer dil örneklerine bakın.

2. Ödemeyi siparişe bağlayın

Doğrulamadan sonra ayrıştırıp siparişi bulun. Nonce, referans, address_in ve coin kontrol edin. trc20/usdt siparişi callback içinde trc20_usdt bekler. Ticker’ı tutardan veya müşteri etiketinden çıkarmayın.

POST gövdeyi imzalar; özel parametreler URL’de kalır. İmza, sorgudaki rastgele sipariş referansını güvenilir yapmaz. Doğrulanmış adresi ve coin alanını siparişle eşleştirmek gerçek gövdenin başka siparişe uygulanmasını engeller.

Sipariş başına tahmin edilemez nonce üretin; tam URL’yi sunucuda saklayın. Loglara erişim sağladığı için analitiğe ve müşteri bağlantılarına koymayın. Nonce eşleştirmeye yardım eder ama yakalanmış olayın yeni olduğunu kanıtlamaz.

Tutar uygulamadan pending kontrol edin. Gerçek bekleyen olay teslimata izin vermez; onaylı olayda da tutar kontrolü gerekir. Eksik ödemeler rehberine bakın.

3. Replay’i kalıcı idempotency ile önleyin

Genel callback’lerde zaman damgası ve anahtar kimliği yoktur. Olmayan başlık için beş dakikalık tazelik kontrolü uydurmayın. Yakalanmış istek geçerli kalabilir; yeniden işlenmesi ek etki yaratmamalıdır.

UUID, ödeme kaydı ve sipariş geçişini aynı veritabanı işleminde, UUID benzersizlik kısıtıyla saklayın. Önceden “var mı?” sorgusu eşzamanlılık yarışını önlemez.

  1. Doğrulanmış UUID’yi ekleyin; benzersizlik çakışmasını kabul edilmiş olay sayın.
  2. Siparişi kilitleyin ve uygunsa onaylı tutarı kaydedin.
  3. Yalnızca ileri durum geçişleri uygulayıp kalıcı teslimat işi oluşturun.
  4. Alındı yanıtından önce commit yapın.

İşlem başarısızsa başarı yanıtı vermeyin. Commit sonrası bağlantı koparsa tekrar gelen istek kaydedilmiş UUID’yi bulur ve işi yinelemeden yanıtlar.

UUID tek başına çift teslimatı önler mi?

Aynı olayı iki kez uygulamayı önler. Gerçek iki ödemenin olayları farklıdır; sipariş düzeyinde de benzersiz kalıcı teslimat işi gerekir. İşçiler dış sistemleri çağırırken aynı kuralı korumalıdır.

Bir ödemenin bekleyen ve onaylı olayları farklı UUID taşır. Ödeme düzeyinde durum tutun; geç bekleyen olay onayı bozmasın. Kesinlik rehberi farkı açıklar.

4. Doğru yanıt verin ve tekrarları bekleyin

30 saniye içinde HTTP 200 ve düz *ok* döndürün. Düz ok da harf büyüklüğünden bağımsız kabul edilir. HTTP 204, JSON başarı nesnesi veya yönlendirme eşdeğer değildir. Yönlendirmeler izlenmez; son HTTPS hedefini doğrudan yapılandırın.

İlk gönderim dahil sekiz deneme vardır. Sonraki aralıklar 30 saniye, 2 dakika, 10 dakika, 30 dakika, 2 saat, 6 saat ve 24 saattir; yüzde 10’a kadar ek sapma olabilir. UUID değişmez. Bunlar kesin saat vaatleri değil, ardışık gecikmelerdir.

Yavaş işi istekten çıkarın. Olayı ve teslimat görevini kalıcı kaydedip yanıt verin; paketleme, e-posta veya erişim işi sonra yürüsün. Yalnızca bellek kuyruğu, yanıt sonrası iş kaybını engellemez.

Callback rehberi ayrıntıları verir. İşlenmiş geçerli olay normal başarı yanıtı almalıdır.

5. Anahtar rotasyonunu yönetin

Yapılandırılmış endpoint’ten alınan anahtarı önbellekte tutun. İmza başarısızsa bir kez yenileyip yeniden doğrulayın. Eski olayların tekrarları da yeni anahtarla imzalanır; kimlik yine UUID’dir.

Callback’in verdiği URL’den anahtar almayın, aynı istekte sürekli yenilemeyin. Yeni anahtarın türünü ve boyutunu doğrulayın. Endpoint erişilemiyorsa siparişi değiştirmeyin; doğrulanmamış veriyi kabul etmek yerine yeniden denemeyi bekleyin.

Geçersiz imzaları, doğrulanıp kaydedilemeyen olaylardan ayrı izleyin. Tanı sırasında sır içeren tam callback URL’lerini loglamayın.

6. Eksik callback ve hata yollarını kontrol edin

Özgün callback ile GET /{ticker}/logs/ kullanın. sent, denemeleri tükenmiş olsa da aktarımın onaylandığını ve callback alındısının olmadığını; done alındığını belirtir. Loglar uzlaştırma yedeğidir, normal yol doğrulanmış callback’tir.

Yayımlamadan aynı olayı iki kez iletip tek kalıcı işlem oluştuğunu görün. Bir baytı değiştirip reddedilmesini isteyin. Commit öncesi veritabanı hatasını, commit sonrası yanıt kaybını ve onaylının bekleyenden önce gelmesini deneyin.

İki ayrı siparişle de sınayın: bir ödemenin geçerli imzası diğerini ödememeli. USDT rehberi eşleştirmeyi, TRC20 ve BEP20 ise ağın tutarla birlikte saklanmasını açıklar.