Verifikasi & Idempotensi Tanda Tangan Webhook

Webhook memberi tahu backend mitra tentang perubahan status bisnis asinkron. Karena pengiriman dapat dicoba ulang, setiap penerima harus memverifikasi tanda tangan sebelum mem-parse data tepercaya dan harus memproses peristiwa secara idempotensial.

Header Webhook

Header	Deskripsi
X-Agent-Timestamp	Timestamp Unix dalam hitungan detik.
X-Agent-Nonce	Perlindungan tayangan ulang nonce.
tanda tangan agen x	HMAC- tanda tanganSHA256 .

timestamp + nonce + rawBody

Gunakan body permintaan mentah yang diterima secara tepat selama HTTP saat merekonstruksi nilai yang ditandatangani. Mengurai dan menyeriakan ulang JSON terlebih dahulu dapat mengubah urutan ruang kosong atau field dan menghasilkan tanda tangan yang berbeda.

Alur verifikasi

Baca timestamp, nonce, dan header tanda tangan.
Tangkap badan permintaan mentah yang tidak dimodifikasi.
Bangun timestamp + nonce + rawBody.
Hitung HMAC-SHA256 dengan mitra API rahasia.
Bandingkan tanda tangan yang dihitung dan diterima menggunakan perbandingan waktu konstan.
Terapkan timestamp-freshness dan nonce-reuse yang disetujui.
Analisis dan proses event hanya setelah verifikasi berhasil.

Ketika verifikator Agent SDK resmi tersedia, gunakan itu daripada mempertahankan kode penandatanganan independen.

Idempotensi urutan

Kasus	Penanganan
Permintaan transfer awal	Buat satu agentOrderNoyang unik secara global.
HTTP timeout	Query agentOrderNo asli sebelum membuat yang baru.
Respons PROCESSING	Tunggu status webhook atau urutan kueri.
Webhook berulang	Deduplikasi berdasarkan kunci idempotensi dan status akhir.

Catatan idempotensi yang direkomendasikan

Simpan cukup informasi untuk mengenali pengiriman berulang dan pulihkan dengan aman:

Lapangan	Tujuan
Kunci acara atau bisnis	Mengidentifikasi notifikasi atau operasi secara unik.
Nomor pesanan mitra	Menghubungkan event ke permintaan asli.
Hash payload	Membantu mengidentifikasi muatan berulang yang bertentangan.
Status pemrosesan saat ini	Distinguishes yang diterima, diproses, berhasil, dan gagal dalam pekerjaan.
Status bisnis akhir	Mencegah aksi terminal diterapkan dua kali.
Timestamp yang diproses	Mendukung kebijakan investigasi dan retensi.

Commit catatan perubahan bisnis dan idempotensi dalam transaksi yang sama jika memungkinkan. Peristiwa berulang harus mengembalikan hasil yang sudah diketahui, bukan menerapkan saldo, pesanan, atau perubahan pengguna lagi.

Aturan timeout dan percobaan ulang

Timeout HTTP tidak membuktikan bahwa permintaan asli gagal. Query operasi menggunakan agentOrderNoasli, atau tunggu webhook-nya, sebelum memutuskan apakah tindakan lain diperlukan. Membuat nomor order bisnis baru setelah setiap timeout dapat menyebabkan pergerakan dana duplikat.

Daftar periksa produksi

Verifikasi tanda tangan sebelum JSON parsing atau pemrosesan bisnis.
Menjaga badan mentah secara independen dari muatan yang telah diparse.
Tolak permintaan yang sudah usang atau diputar ulang sesuai dengan kebijakan integrasi yang telah disetujui.
Membuat pemrosesan acara aman untuk pengiriman berulang maupun di luar urutan.
Catat event ID, nomor pesanan mitra, hasil pemrosesan, dan waktu permintaan.
Menyusun rahasia dan nilai tanda tangan dari log dan lampiran dukungan.

Rahasia & Penandatanganan HMAC

Lindungi rahasia API yang digunakan untuk verifikasi permintaan dan webhook.

Agent SDK Ikhtisar

Tinjau alur kerja integrasi backend secara lengkap.

SDK Pemecahan Masalah