Webhook İmza Doğrulama ve İdempotensi

Webhooks eş arka uçunu asenkron iş durumu değişiklikleri hakkında bilgilendirir. Teslimat tekrar denenebildiği için, her alıcı güvenilir verileri ayrıştırmadan önce imzayı doğrulamalı ve olayı ikametsiz bir şekilde işlemek zorundadır.

Webhook başlıklar

Başlık	Tanım
X-Ajan-Zaman Damgası	Unix zaman damgası saniyelerde.
X-Ajan-Nonce	Tekrar oynatma koruması yok.
X-Ajan-İmzası	HMAC-SHA256 imzası.

timestamp + nonce + rawBody

İmzalanmış değeri yeniden oluştururken HTTP üzerinden alınan tam ham istek gövdesini kullanın. İlk olarak JSON ayrıştırıp yeniden serileştirmek, boşluk veya alan sırasını değiştirebilir ve farklı bir imza üretebilir.

Doğrulama akışı

Zaman damgası, nonce ve imza başlıklarını okuyun.
Değiştirilmemiş ham istek gövdesini ele geçir.
Build timestamp + nonce + rawBody.
Hesapla HMAC-SHA256 partnerle API sır.
Hesaplanan ve alınan imzaları sabit zamanlı bir karşılaştırma ile karşılaştırın.
Onaylanmış zaman damgası-tazelik ve tekrar kullanmama kontrolleri uygulanır.
Olayı ancak doğrulama başarılı olduktan sonra ayrıştırıp işleyin.

Resmi bir Agent SDK doğrulayıcı mevcut olduğunda, bağımsız imza kodunu korumak yerine onu kullanın.

Order idempotency

Dava	Yol tutuşu
İlk transfer isteği	Küresel olarak benzersiz bir agentOrderNooluşturun.
HTTP mola	Yeni bir agentOrderNo oluşturmadan önce orijinal sorgulayın.
PROCESSING yanıtı	webhook veya sipariş durumunu sorgulayın.
Tekrarlayan webhook	Idempotency anahtarı ve nihai duruma göre deduplicate.

Önerilen idempotency kaydı

Tekrarlanan teslimatı tanıyacak kadar bilgi depolayın ve güvenli bir şekilde kurtarın:

Saha	Amaç
Etkinlik veya iş anahtarı	Bildirimi veya işlemi benzersiz şekilde tanımlar.
Ortak sipariş numarası	Etkinliği orijinal isteğe bağlar.
Yük hash	Çelişkili tekrarlayan yükleri tespit etmeye yardımcı olur.
Mevcut işlem durumu	Alınan, işlenen ve başarısız olan çalışmaları ayırt eder.
Son iş durumu	Terminal bir eylemin iki kez uygulanmasını engeller.
İşlenen zaman damgası	Soruşturma ve tutma politikalarını destekler.

Mümkün olduğunda aynı işlemde iş değişikliği ve idempotency kaydını taahhüt edin. Tekrarlanan bir olay, bakiye, sipariş veya kullanıcı değişikliğini tekrar uygulamak yerine zaten bilinen sonucu geri getirmelidir.

Mola ve yeniden deneme kuralı

HTTP bir zaman aşımı orijinal talebin başarısız olduğunu kanıtlamaz. Operasyonu orijinal agentOrderNoile sorgulayın veya başka bir eylemin gerekip gerekmediğine karar vermeden önce webhookbekleyin. Her zaman bitiminden sonra yeni bir iş siparişi numarası oluşturmak, fonların tekrarlanmasına neden olabilir.

Üretim kontrol listesi

Ayrıştırma veya iş işleme öncesi imzayı JSON doğrulamak.
Ham gövdeyi ayrıştırılmış yükten bağımsız olarak korumak.
Onaylanmış entegrasyon politikasına göre eski veya tekrar oynanan talepleri reddetmek.
Etkinlik işleme süreçlerini tekrarlanan ve sırasız teslimatlar için güvenli hale getirmek.
Etkinlik kimliklerini, ortak sipariş numaralarını, işlem sonuçlarını ve istek zamanını kaydet.
Loglardan ve destek eklerinden sırlar ve imza değerlerini mantıklayın.

Sırlar ve HMAC İmzalama

Talep ve doğrulama için kullanılan API sırrı koruyun webhook doğrulama.

Agent SDK Genel Bakış

Tam arka uç entegrasyon iş akışını gözden geçirin.

SDK Sorun Giderme