Webhook İmza Doğrulaması ve Kimlik Yetkisi

Bu sayfa takip ediyor Agent Java SDK WEBHOOKS.md taahhüt sırasında fa6c7b6. Bu yalnızca belgelere yönelik bir güncelleştirmedir; uyarı yardımcı yöntemlerini içeren yeni bir SDK yapı yayınlanmadı.

Dört olay türünün tümü bir satıcı geri aramasını URL kullanır ve gövde event tarafından gönderilir. Görmek Webhook Etkinlikler ve Tasfiye Uyarıları olay alanları ve yük örnekleri için.

Webhook başlıkları

timestamp + nonce + rawBody

Olay belirsizliği

Ticari işlemlerle atomik olarak satıcı ve environment kapsamında tekilleştirmeye devam edin. Farklı notificationId değerleri, bağımsız FIRST / UPGRADE / REMINDER bildirimlerini tanımlar; bildirimleri kullanıcıya, bölüme veya eventType’e göre gruplayarak atmayın. Tekilleştirme için boş bir idempotency anahtarı kullanılamaz. SDK yalnızca bir yardımcı anahtar döndürür; iş verilerini sürdürmez veya işlemez. Aynı kimliği farklı bir bedenle çatışma olarak kaydedin; işlenen gövdenin üzerine yazmayın.

İmza doğrulama ve alma

API tüccarının HMAC-SHA256 onaltılı imzasını hesaplamak için timestamp + nonce + rawBody sırrını kullanın. Orijinal alınan baytları doğrulayın; JSON biçimlendirmeyin, alanları yeniden adlandırmayın veya önce gövdeyi yeniden serileştirmeyin.

Önce imzayı doğrulayın, ardından zaman penceresini (önerilen ±300 saniye), satıcıyı ve ortamı kontrol edin. Daha sonra idempotency kimliğini çıkarın ve bildirimi güvenilir bir şekilde işleyin. Teşhis için bilinmeyen olay değerlerini koruyun; bunları asla fon başarısı olarak yorumlamayın. Doğrulama yardımcısı zaman penceresi, sahiplik veya kalıcı veri tekilleştirme kontrolleri gerçekleştirmez.

İşlemeyi tamamladıktan veya aynı kopyayı onayladıktan sonra HTTP 2xx’i döndürün; başarısızlık durumunda 2xx olmayanı döndür. Uyarıyı gönderenin 5 saniyelik HTTP zaman aşımı ve en fazla 8 denemesi vardır. Yeniden denemeler donmuş gövdeyi korur; yalnızca imza zaman damgası ve bir kez değişiklik olmaz. Güvenilir kabulün ardından derhal yanıt verin; uzun süredir devam eden iş çalışmaları, tüccarın kendi kalıcı görevlerini kullanabilir.

Satıcı bildirimleri kullanıcının çevrimiçi durumuna bağlı değildir. Platform kullanıcılarının gönderimleri yalnızca çevrimiçi olarak en iyi çabayla gerçekleştirilir ve çevrimdışı tekrar oynatılmaz; birinci aşamada bildirim gelen kutusu yoktur.

Başarılı yanıtlar ve yeniden denemelerin durdurulması

Fon geri aramaları ve tasfiye uyarıları, teslimat başarısını belirlemek için yalnızca HTTP durum kodunu kullanır. Gönderen, yanıt gövdesini code, success, result veya message yorumlamaz ve sabit bir OK / success yanıtı gerektirmez.

Yanıt gövdesi boş, metin veya JSON olabilir. Örnek result alanları protokol gereksinimleri için değil, satıcı için bilgi amaçlıdır. 202 Accepted ayrıca platformun yeniden denemelerini de durdurur; bu nedenle, yalnızca bellek içi eşzamansız bir görevi başlatmakla kalmayıp, yalnızca bildirimi satıcının kalıcı görev kuyruğuna güvenilir bir şekilde kaydettikten sonra geri döndürün.

Başarılı yanıt örnekleri

İş süreci tamamlandıktan veya bildirim satıcının bekleme kuyruğuna güvenilir bir şekilde kaydedildikten sonra:

HTTP/1.1 200 OK
Content-Type: application/json
{"result":"RECEIVED"}

Yanıt kuruluşuna ihtiyaç duyulmadığında:

HTTP/1.1 204 No Content

Aynı gövdeye sahip önceden işlenmiş bir bildirim için, yinelenen iş işlemeyi atlayın ve yine de 2xx değerini döndürün:

HTTP/1.1 200 OK
Content-Type: application/json
{"result":"DUPLICATE"}

Arıza yanıtı örnekleri

Veritabanı geçici olarak kullanılamıyorsa ve satıcı işlemi tamamlamamışsa veya bildirimi güvenilir bir şekilde kaydetmemişse platformun yeniden deneyebilmesi için 2xx olmayanı döndürün:

HTTP/1.1 503 Service Unavailable
Content-Type: application/json
{"result":"FAILED","message":"temporary storage failure"}

İş verilerini veya başarılı veri tekilleştirme kayıtlarını güncellemeden geçersiz bir imzayı reddedin:

HTTP/1.1 401 Unauthorized
Content-Type: application/json
{"result":"INVALID_SIGNATURE"}

Bu yanıt organları yeniden deneme kararlarını değiştirmez. 401 veya 409’un yeniden denemeleri kalıcı olarak durdurmasını beklemeyin; imzayı, bildirim içeriğini veya satıcı yapılandırmasını araştırın.

Yanlış örnek: Aşağıdaki yanıt hâlâ başarılı teslimat olarak sayılıyor. Platform success:false nedeniyle yeniden denemeyecek.

HTTP/1.1 200 OK
Content-Type: application/json
{"success":false,"code":500,"message":"processing failed"}

Çerçeve veya genel istisna işleyicisi iş hatalarını HTTP 200’de sararsa, geri çağırma uç noktasında doğru hata durumunu açıkça ayarlayın.

Güvenilir onay ve kopya teslimat

Önerilen sıra: imzayı doğrulayın ve zamanı / tüccarı / ortamı kontrol edin → yetersizlik kimliğini çıkarın → bir işlemde iş verilerini ve başarılı veri tekilleştirme kayıtlarını işleyin veya bekleyen bir görevi güvenilir bir şekilde kaydedin → taahhüt başarılı olduktan sonra 200/204’ü döndürün. Başarılı bir veritabanı yazma işleminden önce 2xx döndürmeyin veya işlenen bildirimi işaretlemeyin.

Satıcının işlemesi başarılı olduktan sonra yinelenen teslimat gerçekleşebilir: yanıt kaybolabilir veya platform 2xx alabilir ancak SUCCESS devam edemeyebilir. HTTP geri aramalar tek seferlik teslimatı garanti etmez. Satıcı ve environment kapsamında tekilleştirmeye devam edin. Fonlar orderType:orderId:targetStatus kullanır; uyarılarda liquidation.warning:notificationId kullanılır. Zaten işlenmiş aynı gövde için, 2xx’i para yatırmadan veya tekrar hatırlatmada bulunmadan iade edin. Farklı bir gövdeyle aynı kimlik için bir çakışma kaydedin ve 2xx olmayanı döndürün; orijinal kaydın üzerine yazmayın.

Onay başarısı, ödeme işleminin başarılı olduğu anlamına gelmez, satıcının bildirimi aldığı/işlediği anlamına gelir. Geçerli bir fon bildirimini targetStatus=FAILED ile kaydettikten sonra ayrıca 2xx değerini döndürün; Siparişin başarısız olması, bildirim onayının reddedilmesi için bir neden değildir.

Finansman ve çevre sınırları

Orijinal Sözleşme transferi webhook ve queryOrder akışı, Finansmana otomatik olarak uygulanmaz. Finansman işlemlerini queryWalletTransfer ve orijinal sipariş ortamını kullanarak onaylayın. Finansmanda status kullanılır; Orijinal Sözleşme aktarım yanıtlarında orderStatus kullanılır. Başarılı bir HTTP yanıtı veya code=0 tek başına fonların taşındığını kanıtlamaz.

Açık simüle edilmiş Sözleşme aktarım bildirimleri arasında environment=SIMULATED bulunur. Önce ham gövdeyi doğrulayın, ardından kullanıcıyı, tutarı, sipariş kimliğini ve ortamı kaydedilen yerel iş emriyle karşılaştırarak kontrol edin.

Finansman kurtarma kılavuzu · Çevre kılavuzu