Webhook Pembayaran Kripto: Event, Keamanan, dan Pemenuhan Pesanan yang Andal

Webhook pembayaran kripto adalah permintaan HTTP yang dikirim payment gateway ke servermu setiap kali status invoice berubah: transfer terdeteksi, terkonfirmasi di rantai, kurang bayar, lebih bayar, atau kedaluwarsa. Handler-mu memverifikasi tanda tangan, memperbarui pesanan, dan memicu pengiriman. Karena pembayaran kripto datang secara asinkron, beberapa menit setelah pelanggan meninggalkan halamanmu, sumber kebenarannya adalah webhook, bukan browser.

Panduan ini berfokus pada sisi webhook dari integrasi: event yang akan diterima, cara memverifikasinya, cara memproses dengan aman saat event yang sama datang dua kali, serta cara menguji dan memantaunya. Untuk membuat invoice, lihat panduan integrasi API pembayaran kripto.

Mengapa webhook, bukan polling atau redirect?

• Redirect bukan bukti — pelanggan kembali ke halaman "terima kasih" tidak menunjukkan apakah uang sudah masuk.
• Polling boros — menanyakan API setiap beberapa detik untuk setiap invoice terbuka tidak bisa diskalakan dan tetap terlambat.
• Webhook bersifat push — gateway memberi tahu begitu ada perubahan, dengan tanda tangan yang bisa diverifikasi.

Event yang akan kamu terima

Ini adalah nama event di mistKET. Gateway lain memakai status serupa dengan nama berbeda, jadi petakan ke status pesananmu di satu tempat.

Memverifikasi tanda tangan

Siapa pun bisa mengirim POST ke URL publik, jadi setiap webhook harus diautentikasi. mistKET menandatangani setiap pengiriman dengan HMAC-SHA256 dan mengirim header berikut:

• X-Mistket-Event — nama event.
• X-Mistket-Timestamp — waktu Unix yang ikut ditandatangani.
• X-Mistket-Signature — sha256= diikuti HMAC dari {timestamp}.{raw body} dengan secret webhook-mu.
• X-Mistket-Delivery — ID pengiriman untuk logging.

1. Baca raw body — sebelum parsing JSON, karena encoding ulang mengubah byte.
2. Hitung ulang HMAC — dari timestamp, titik, dan raw body dengan secret webhook-mu.
3. Bandingkan dalam waktu konstan — gunakan hash_equals, hmac.compare_digest, atau crypto.timingSafeEqual.
4. Tolak timestamp lama — misalnya lebih dari lima menit, untuk mencegah replay.
5. Baru kemudian parse dan proses — lalu balas 2xx dengan cepat.

Konstruksinya mengikuti pola standar HMAC; simpan secret di server dan ganti jika pernah bocor.

Memilih dan melindungi URL callback

Gunakan path HTTPS khusus seperti /webhooks/mistket, terpisah dari halaman biasa, dan kirimkan sebagai callback URL saat membuat setiap invoice. Kecualikan path ini dari proteksi CSRF, cache, dan redirect; redirect 301 atau respons dari cache adalah penyebab umum webhook gagal diam-diam. Jangan wajibkan cookie sesi; gateway bukan pengguna yang login, autentikasinya adalah tanda tangan HMAC. Terakhir, catat setiap pengiriman beserta event, ID pesanan, dan kode respons agar pertanyaan "webhook-nya masuk atau tidak?" bisa dijawab dalam hitungan detik.

Idempotensi: event yang sama bisa datang dua kali

Jika endpoint-mu timeout atau mengembalikan error, gateway mencoba lagi dengan jeda yang makin panjang selama berjam-jam. Gangguan jaringan juga bisa mengirim ulang event yang sudah diproses. Karena itu handler-mu harus idempoten:

• Gunakan ID pesanan sebagai kunci — cari pesanan yang dirujuk invoice.
• Periksa status saat ini — jika pesanan sudah dipenuhi, cukup akui dan jangan lakukan apa pun.
• Gunakan transaksi atau lock — agar dua pengiriman paralel tidak sama-sama mengirim produk.
• Simpan ID pengiriman — berguna untuk men-debug duplikat.

Merancang status pesanan berdasarkan event

State machine sederhana mencegah sebagian besar bug: menunggu → dikonfirmasi (saat paid) → dibayar (saat confirmed) → dipenuhi, dengan cabang untuk kurang bayar dan kedaluwarsa. Hanya izinkan transisi maju. invoice.paid yang datang setelah invoice.confirmed tidak boleh memundurkan pesanan. Pembayaran terlambat ke invoice yang kedaluwarsa sebaiknya membuat catatan untuk ditinjau, bukan membuka ulang pesanan diam-diam.

Menangani kasus yang merepotkan

• Kurang bayar — beri tahu pelanggan jumlah kekurangannya dan bahwa mereka bisa mengirimnya ke halaman pembayaran yang sama; pembayaran parsial dijumlahkan.
• Lebih bayar — penuhi pesanan, lalu putuskan kredit saldo atau transfer refund sesuai kebijakanmu.
• Kedaluwarsa — lepas stok dan tawarkan invoice baru jika pelanggan masih ingin membeli.
• Jaringan salah — ditangani tim dukungan, bukan kode; tampilkan jaringan dengan jelas di checkout untuk mencegahnya.

Pengujian dan pemantauan

1. Siapkan endpoint uji — via HTTPS, dengan logging header dan raw body.
2. Picu setiap event — paid, confirmed, underpaid, overpaid, dan expired dengan pembayaran nyata yang kecil.
3. Ulangi satu pengiriman — pastikan handler mengabaikan duplikat.
4. Rusak tanda tangan — ubah satu byte dan pastikan permintaan ditolak.
5. Pantau log pengiriman — panel merchant menampilkan setiap percobaan, kode respons, dan hash transaksi.
6. Pasang peringatan kegagalan — lonjakan respons non-2xx berarti pesanan tidak terpenuhi.

Bot dan komunitas berbayar mengikuti pola yang sama; lihat penerapannya dalam alur chat di menerima pembayaran kripto di bot Telegram.

Webhook dengan mistKET

mistKET mengirim webhook bertanda tangan HMAC untuk setiap status invoice, mengulang pengiriman yang gagal dengan jeda bertahap, dan menampilkan log pengiriman, jumlah yang diharapkan dan diterima, serta hash transaksi di panel merchant. Permintaan ke API ditandatangani dengan cara yang sama, jadi satu fungsi bantu mencakup kedua arah.

Lihat contoh permintaan dan webhook di bagian pengembang, cek harga, dan kelola kunci dari login merchant. Untuk mendapatkan akses, daftar lewat Telegram di @mistnetwork.