Apa Itu Webhook Pembayaran dan Cara Mengamankannya

Setiap kali pelanggan menyelesaikan pembayaran, sistem Anda perlu tahu secepat mungkin. Webhook pembayaran adalah cara paling andal untuk mendapatkan kabar itu: alih-alih aplikasi Anda menanyakan status terus-menerus, penyedia pembayaran yang akan "menelepon balik" server Anda begitu ada perubahan status. Artikel ini menjelaskan apa itu webhook pembayaran, mengapa ia lebih efisien dari polling, dan bagaimana mengamankannya dengan verifikasi tanda tangan HMAC, idempotensi, serta penanganan retry agar transaksi tidak pernah terlewat atau terproses ganda.

Apa Itu Webhook Pembayaran?

Webhook adalah HTTP request otomatis yang dikirim penyedia pembayaran ke URL (endpoint) di server Anda ketika suatu peristiwa terjadi. Bayangkan webhook sebagai "pemberitahuan push" antar-server: Anda mendaftarkan sebuah alamat, lalu setiap kali ada peristiwa penting, penyedia mengirim data peristiwa itu ke alamat tersebut dalam format JSON.

Dalam konteks pembayaran, peristiwa yang paling penting biasanya adalah:

• payment.paid — pembayaran berhasil diterima.
• payment.expired — kode pembayaran kedaluwarsa sebelum dibayar.
• payment.failed — pembayaran gagal diproses.

Begitu server Anda menerima webhook, Anda bisa langsung menjalankan aksi bisnis: menandai pesanan lunas, mengirim email atau pesan WhatsApp ke pelanggan, membuka akses ke produk digital, atau memicu proses pengiriman. Semua terjadi dalam hitungan detik tanpa perlu ada orang yang memantau dashboard.

Di BorderPay, notifikasi webhook ditandatangani dengan HMAC dan setiap pengiriman tercatat di log, lengkap dengan opsi kirim ulang bila server Anda sempat tidak merespons. Detail teknis payload dan header ada di dokumentasi.

Kenapa Webhook Lebih Andal daripada Polling?

Sebelum webhook populer, cara umum mengetahui status pembayaran adalah polling: aplikasi Anda memanggil API penyedia berulang kali ("Sudah dibayar belum? Sudah dibayar belum?") sampai statusnya berubah. Polling punya beberapa masalah nyata:

• Boros sumber daya. Ratusan atau ribuan permintaan status dikirim padahal sebagian besar jawabannya "belum berubah".
• Ada jeda. Jika Anda polling tiap 30 detik, pelanggan bisa menunggu hingga setengah menit sebelum sistem menyadari pembayaran sukses.
• Rentan kena rate limit. Terlalu sering memanggil API bisa membuat permintaan Anda diblokir sementara.

Webhook membalik model ini. Server Anda diam saja sampai benar-benar ada kabar, lalu penyedia yang mengirim pemberitahuan tepat saat status berubah. Hasilnya: lebih hemat, lebih cepat, dan lebih real-time.

Satu catatan: karena webhook adalah permintaan masuk dari luar, ia butuh pengamanan yang lebih serius. Di sinilah tiga pilar berikut berperan.

Cara Mengamankan Webhook Pembayaran dengan Verifikasi HMAC

Endpoint webhook Anda pada dasarnya adalah URL publik. Siapa pun yang tahu alamatnya bisa mengirim request palsu yang mengaku "pembayaran sukses". Kalau Anda memercayai request mentah-mentah, penipu bisa membuat pesanan tampak lunas tanpa benar-benar membayar. Karena itu, jangan pernah memercayai isi webhook sebelum diverifikasi.

Cara standar memverifikasinya adalah dengan tanda tangan HMAC (Hash-based Message Authentication Code). Mekanismenya:

1. Penyedia dan Anda sama-sama memegang sebuah secret (kunci rahasia yang hanya kalian berdua tahu).
2. Saat mengirim webhook, penyedia menghitung hash dari isi payload menggunakan secret tersebut, lalu menaruh hasilnya di header request (misalnya sebagai tanda tangan/signature).
3. Server Anda menghitung ulang hash dari payload yang diterima, memakai secret yang sama.
4. Jika tanda tangan yang Anda hitung sama persis dengan yang dikirim penyedia, berarti request itu asli dan tidak diubah di tengah jalan. Jika berbeda, tolak request (balas dengan status error dan abaikan datanya).

Beberapa praktik penting saat verifikasi:

• Bandingkan tanda tangan dengan cara yang aman. Gunakan fungsi perbandingan yang tahan timing attack (constant-time comparison) alih-alih == biasa bila bahasa Anda menyediakannya.
• Hitung hash dari body mentah. Verifikasi menggunakan payload asli (raw bytes) sebelum di-parse ulang, karena perubahan format sekecil apa pun akan mengubah hash.
• Simpan secret dengan aman. Taruh di environment variable atau secret manager, jangan di dalam kode sumber yang bisa bocor ke repositori.
• Batasi endpoint hanya menerima HTTPS. Ini mencegah payload dan header disadap di perjalanan.

Dengan verifikasi HMAC, Anda memastikan setiap webhook yang diproses benar-benar berasal dari penyedia pembayaran, bukan dari pihak lain. Ini adalah fondasi keamanan integrasi yang tidak boleh dilewati.

Idempotensi: Aman meski Webhook Datang Dua Kali

Realita jaringan tidak sempurna. Kadang server Anda sudah menerima dan memproses webhook, tetapi jawaban "sukses" dari server Anda tidak sampai kembali ke penyedia tepat waktu. Dari sisi penyedia, itu tampak seperti pengiriman gagal, sehingga webhook yang sama dikirim ulang. Akibatnya, server Anda bisa menerima peristiwa payment.paid yang identik lebih dari sekali.

Kalau logika Anda tidak siap, ini berbahaya: satu pembayaran bisa dihitung dua kali, satu produk dikirim ganda, atau satu saldo ditambahkan berlipat. Solusinya adalah idempotensi — merancang penanganan agar memproses peristiwa yang sama berulang kali menghasilkan efek yang sama seperti memproses sekali.

Cara umum menerapkannya:

• Setiap peristiwa webhook biasanya membawa ID unik (misalnya ID pembayaran atau ID event).
• Sebelum menjalankan aksi bisnis, cek apakah ID itu sudah pernah diproses (misalnya dengan mencatatnya di tabel database dan memberi unique constraint).
• Jika sudah ada, balas sukses tanpa menjalankan aksi lagi. Jika belum, proses lalu catat ID-nya dalam transaksi yang sama.

Pola ini membuat sistem Anda tahan terhadap duplikasi tanpa menolak retry yang sah. Idempotensi adalah pasangan wajib dari mekanisme retry yang akan kita bahas berikutnya.

Menangani Retry dengan Benar

Karena webhook bisa gagal terkirim, penyedia yang baik akan mencoba mengirim ulang. Agar mekanisme retry bekerja mulus, endpoint Anda perlu mengikuti beberapa aturan:

• Balas cepat dengan status 2xx. Kirim respons 200 segera setelah Anda menerima dan menyimpan peristiwa. Jangan menunggu proses berat (kirim email, panggil API lain) selesai dulu — lakukan itu secara asinkron di belakang. Respons yang lambat bisa dianggap gagal dan memicu retry yang tidak perlu.
• Balas non-2xx bila memang gagal. Jika Anda belum bisa memproses (misalnya database sedang tidak tersedia), balas dengan status error agar penyedia mencoba lagi nanti — bukan menelan error diam-diam.
• Gabungkan dengan idempotensi. Retry hanya aman kalau penanganan Anda idempoten. Keduanya adalah pasangan yang tak terpisahkan.

Di BorderPay, riwayat pengiriman webhook tercatat sehingga Anda bisa melihat mana yang berhasil dan mana yang perlu dikirim ulang, lalu memicu pengiriman ulang manual bila diperlukan. Ini berguna saat Anda baru selesai memperbaiki bug di endpoint dan ingin "memutar ulang" peristiwa yang sempat gagal.

Menguji Webhook Sebelum Go-Live

Jangan pernah menyalakan webhook langsung di lingkungan produksi tanpa uji coba. BorderPay menyediakan mode test/sandbox yang bisa dipakai sejak hari pertama — Anda bisa memicu peristiwa pembayaran tiruan dan memastikan endpoint Anda memverifikasi tanda tangan, menangani duplikasi, serta membalas dengan benar, semuanya tanpa uang sungguhan. Untuk mulai menerima uang sungguhan, Anda perlu menyelesaikan proses KYC terlebih dahulu.

Perlu diingat juga: di BorderPay, QRIS berlaku 60 menit dan Virtual Account berlaku 24 jam. Setelah itu status otomatis menjadi kedaluwarsa dan Anda akan menerima webhook payment.expired — pastikan aplikasi Anda menanganinya, misalnya dengan menutup pesanan yang tak kunjung dibayar.

Menempatkan Webhook dalam Alur Integrasi Anda

Webhook adalah komponen inti hampir semua metode integrasi. Jika Anda memakai REST API untuk membuat pembayaran secara dinamis, webhook-lah yang memberi tahu hasilnya. Bahkan bila Anda memilih pendekatan lebih sederhana seperti Embed Checkout atau payment link, webhook tetap berguna untuk sinkronisasi status ke sistem internal Anda. Untuk mengenal opsi discovery seperti GET /payment-methods dan detail endpoint lain, lihat dokumentasi.

BorderPay adalah lapisan teknologi (software) di atas mitra Payment Gateway yang berlisensi Bank Indonesia; pemrosesan dan penyimpanan dana dilakukan oleh mitra berlisensi tersebut. Yang BorderPay sediakan adalah pengalaman integrasi yang rapi — termasuk webhook bertanda tangan, log, dan kirim ulang — sehingga tim Anda bisa fokus membangun produk.

Ringkasan

Webhook pembayaran mengubah cara aplikasi Anda mengetahui status transaksi: dari polling yang boros menjadi notifikasi real-time yang efisien. Agar aman dan andal, tiga hal wajib ada di sisi merchant — verifikasi tanda tangan HMAC untuk memastikan keaslian, idempotensi agar peristiwa ganda tidak diproses dua kali, dan penanganan retry yang membalas cepat serta jujur soal keberhasilan. Terapkan ketiganya, uji di sandbox, dan integrasi pembayaran Anda akan tangguh sejak awal.

Siap mencoba? Daftar gratis dan mulai eksplorasi di mode test — tanpa biaya pendaftaran atau langganan, biaya hanya muncul saat transaksi. Lihat rinciannya di halaman pricing, atau baca pertanyaan umum di FAQ.