Webhook Verifikasi & Idempotensi Tanda Tangan

Halaman ini mengikuti Agent Java SDK WEBHOOKS.md saat melakukan fa6c7b6. Ini adalah pembaruan dokumentasi saja; tidak ada artefak SDK baru yang berisi metode pembantu peringatan yang dirilis.

Keempat jenis peristiwa menggunakan satu panggilan balik pedagang URL dan dikirim oleh isi event. Melihat Webhook Peristiwa & Peringatan Likuidasi untuk bidang acara dan contoh muatan.

Webhook header

timestamp + nonce + rawBody

Idempotensi peristiwa

Pertahankan deduplikasi dalam lingkup pedagang dan environment, secara atomik dengan pemrosesan bisnis. Nilai notificationId yang berbeda mengidentifikasi notifikasi FIRST / UPGRADE / REMINDER independen; jangan membuang notifikasi dengan mengelompokkan berdasarkan pengguna, episode, atau eventType. Kunci idempotensi yang kosong tidak dapat digunakan untuk deduplikasi. SDK hanya mengembalikan kunci pembantu; itu tidak menyimpan atau memproses data bisnis. Mencatat identitas yang sama dengan badan yang berbeda sebagai konflik; jangan menimpa tubuh yang diproses.

Verifikasi dan penerimaan tanda tangan

Gunakan rahasia pedagang API untuk menghitung HMAC-SHA256 tanda tangan heksadesimal dari timestamp + nonce + rawBody. Verifikasi byte asli yang diterima; jangan memformat JSON, mengganti nama kolom, atau membuat serial ulang isi terlebih dahulu.

Verifikasi tanda tangan terlebih dahulu, lalu periksa rentang waktu (disarankan ±300 detik), pedagang, dan lingkungan. Selanjutnya ekstrak identitas idempotensi dan tangani notifikasi dengan andal. Pertahankan nilai peristiwa yang tidak diketahui untuk diagnosis; jangan pernah menafsirkannya sebagai kesuksesan dana. Pembantu verifikasi tidak melakukan pemeriksaan jangka waktu, kepemilikan, atau deduplikasi terus-menerus.

Kembalikan HTTP 2xx setelah menyelesaikan pemrosesan atau mengonfirmasi duplikat yang identik; kembalikan non-2xx jika gagal. Pengirim peringatan mempunyai batas waktu HTTP 5 detik dan paling banyak 8 kali percobaan. Percobaan ulang mempertahankan tubuh yang membeku; hanya stempel waktu tanda tangan dan nonce yang berubah. Tanggapi segera setelah penerimaan yang dapat diandalkan; pekerjaan bisnis jangka panjang dapat menggunakan tugas-tugas terus-menerus dari pedagang itu sendiri.

Notifikasi merchant tidak bergantung pada status online pengguna. Dorongan pengguna platform hanyalah penyampaian upaya terbaik secara online, tanpa pemutaran ulang offline; fase satu tidak memiliki kotak masuk notifikasi.

Respons berhasil dan menghentikan percobaan ulang

Panggilan balik dana dan peringatan likuidasi hanya menggunakan kode status HTTP untuk menentukan keberhasilan pengiriman. Pengirim tidak menafsirkan isi respons code, success, result, atau message, dan tidak memerlukan respons OK / success yang tetap.

Isi respons mungkin kosong, teks, atau JSON. Contoh kolom result bersifat informasi bagi pedagang, bukan persyaratan protokol. 202 Accepted juga menghentikan percobaan ulang platform, jadi kembalikan hanya setelah menyimpan notifikasi dengan andal ke antrean tugas persisten penjual, bukan hanya memulai tugas asinkron dalam memori.

Contoh respons yang berhasil

Setelah pemrosesan bisnis selesai, atau notifikasi telah disimpan dengan andal ke antrean tertunda milik penjual:

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

Ketika tidak diperlukan badan tanggapan:

HTTP/1.1 204 No Content

Untuk notifikasi yang sudah diproses dengan isi yang identik, lewati pemrosesan bisnis duplikat dan tetap kembalikan 2xx:

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

Contoh respon kegagalan

Jika database untuk sementara tidak tersedia dan pedagang belum menyelesaikan pemrosesan atau menyimpan notifikasi dengan andal, kembalikan non-2xx agar platform dapat mencoba lagi:

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

Tolak tanda tangan yang tidak valid tanpa memperbarui data bisnis atau catatan deduplikasi yang berhasil:

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

Badan respons ini tidak mengubah keputusan percobaan ulang. Jangan berharap 401 atau 409 menghentikan percobaan ulang secara permanen; selidiki tanda tangan, konten pemberitahuan, atau konfigurasi pedagang.

Contoh salah: respons berikut masih dihitung sebagai pengiriman berhasil. Platform tidak akan mencoba lagi karena success:false.

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

Jika kerangka kerja atau pengendali pengecualian global membungkus kegagalan bisnis dalam HTTP 200, secara eksplisit tetapkan status kegagalan yang benar pada titik akhir panggilan balik.

Pengakuan yang andal dan pengiriman duplikat

Urutan yang disarankan: verifikasi tanda tangan dan periksa waktu / pedagang / lingkungan → ekstrak identitas idempotensi → proses data bisnis dan catatan deduplikasi yang berhasil dalam suatu transaksi, atau simpan tugas yang tertunda dengan andal → kembalikan 200/204 setelah penerapan berhasil. Jangan kembalikan 2xx atau tandai notifikasi diproses sebelum penulisan database berhasil.

Pengiriman duplikat masih dapat terjadi setelah pemrosesan pedagang berhasil: respons mungkin hilang, atau platform mungkin menerima 2xx tetapi gagal bertahan SUCCESS. HTTP panggilan balik tidak menjamin pengiriman satu kali. Pertahankan deduplikasi dalam lingkup pedagang dan environment. Penggunaan dana orderType:orderId:targetStatus; peringatan gunakan liquidation.warning:notificationId. Untuk badan identik yang sudah diproses, kembalikan 2xx tanpa mengkredit dana atau mengeluarkan pengingat lagi. Untuk identitas yang sama dengan badan berbeda, catat konflik dan kembalikan non-2xx; jangan menimpa catatan aslinya.

Pengakuan berhasil berarti pedagang menerima/memproses pemberitahuan, bukan bahwa pengoperasian dana berhasil. Setelah mencatat notifikasi dana yang valid dengan targetStatus=FAILED, kembalikan juga 2xx; kegagalan pesanan bukan alasan untuk menolak pengakuan pemberitahuan.

Batasan pendanaan dan lingkungan

Alur transfer Kontrak asli webhook dan queryOrder tidak secara otomatis berlaku untuk Pendanaan. Konfirmasikan operasi Pendanaan menggunakan queryWalletTransfer dan lingkungan pesanan asli. Pendanaan menggunakan status; tanggapan transfer kontrak asli menggunakan orderStatus. Respons HTTP yang berhasil atau code=0 tidak dengan sendirinya membuktikan dana telah dipindahkan.

Pemberitahuan transfer Kontrak yang disimulasikan secara eksplisit mencakup environment=SIMULATED. Verifikasi isi mentah terlebih dahulu, lalu periksa pengguna, jumlah, identitas pesanan, dan lingkungan terhadap pesanan bisnis lokal yang disimpan.

Panduan pemulihan pendanaan · Panduan lingkungan