Cara Menguji Webhook Pembayaran di Komputer Lokal (Tunneling)

Uji webhook lokal adalah salah satu langkah yang paling sering bikin developer tersendat saat pertama kali mengintegrasikan pembayaran. Masalahnya sederhana: penyedia pembayaran perlu mengirim notifikasi HTTP ke URL yang bisa diakses dari internet, sedangkan aplikasi yang sedang kamu kembangkan berjalan di localhost yang tidak terlihat dari luar. Akibatnya event seperti payment.paid tidak pernah sampai, dan kamu terjebak menebak-nebak apakah kodenya benar.

Solusinya adalah tunneling: membuat jembatan sementara dari sebuah URL publik ke port di komputermu, sehingga webhook bisa masuk seolah-olah aplikasimu sudah online. Artikel ini menunjukkan cara menyiapkan tunnel dengan ngrok atau cloudflared, mendaftarkan URL webhook, memverifikasi tanda tangan HMAC, lalu memicu event nyata memakai mode sandbox — semua dari mesin lokal.

Kenapa Webhook Tidak Bisa Langsung ke Localhost

Alamat seperti http://localhost:3000 hanya bisa dijangkau dari dalam komputermu sendiri. Server BorderPay dan mitra payment gateway berada di internet publik; mereka tidak tahu jalan menuju laptopmu yang biasanya berada di balik router dan NAT. Tanpa alamat publik, request webhook tidak punya tujuan yang valid.

Tunneling menyelesaikan ini dengan memberi kamu URL publik sementara, misalnya https://acak123.ngrok-free.app, yang meneruskan setiap request ke localhost:3000 di mesinmu. Selama tunnel aktif, webhook yang dikirim ke URL publik itu akan sampai ke endpoint lokal seperti /api/webhook.

Cara ini jauh lebih cepat daripada men-deploy setiap perubahan ke server hanya untuk melihat apakah webhook berfungsi. Kamu bisa memasang breakpoint, membaca log, dan mengubah kode secara langsung sambil event nyata mengalir masuk. Karena tunnel hanya hidup selama proses berjalan, ia juga aman: begitu kamu menutupnya, URL publik itu mati dan tidak ada lagi jalan menuju mesinmu.

Menyiapkan Tunnel dengan ngrok atau cloudflared

Kamu bisa memilih salah satu. Keduanya gratis untuk penggunaan pengembangan.

Opsi 1: ngrok

Setelah menginstal ngrok dan menjalankan aplikasimu di port lokal (misalnya 3000), jalankan:

ngrok http 3000

ngrok akan menampilkan URL Forwarding, misalnya https://acak123.ngrok-free.app -> http://localhost:3000. Salin URL https tersebut.

Opsi 2: cloudflared

Alternatif tanpa perlu akun untuk tunnel cepat:

cloudflared tunnel --url http://localhost:3000

cloudflared akan mencetak URL https://sesuatu.trycloudflare.com. Fungsinya sama seperti ngrok.

Perbandingan singkat keduanya:

Panel inspeksi ngrok di 127.0.0.1:4040 sangat berguna: kamu bisa melihat isi setiap request webhook dan bahkan "replay" untuk menguji ulang tanpa harus memicu pembayaran baru. Kemampuan replay ini menghemat banyak waktu, karena kamu tidak perlu membuat transaksi sandbox baru setiap kali ingin mencoba perbaikan kecil pada handler-mu.

Kalau kamu bekerja dalam tim atau lintas mesin, URL acak yang berganti tiap sesi bisa merepotkan. ngrok berbayar dan sebagian konfigurasi cloudflared memungkinkan URL yang lebih stabil, tetapi untuk pengembangan harian, URL sementara sudah cukup selama kamu ingat memperbarui pendaftaran endpoint saat memulai sesi baru.

Mendaftarkan URL Webhook

Setelah punya URL publik, daftarkan endpoint webhook di pengaturan akunmu, dengan menambahkan path yang menangani notifikasi. Contoh:

https://acak123.ngrok-free.app/api/webhook

Pastikan aplikasimu benar-benar punya route yang menerima POST di path tersebut dan membalas cepat dengan status 200. Kalau server lama merespons, sistem akan menganggap pengiriman gagal dan menjadwalkan kirim ulang. Semua detail payload dan header ada di dokumentasi.

Memverifikasi Tanda Tangan HMAC

Jangan pernah memercayai request yang masuk hanya karena ia menyentuh URL webhookmu. Siapa pun yang tahu URL itu bisa mengirim data palsu. Karena itu setiap webhook BorderPay ditandatangani dengan HMAC, dan tugasmu adalah memverifikasinya sebelum memproses.

Alurnya:

1. Ambil header tanda tangan dari request.
2. Hitung ulang HMAC dari raw body (bukan hasil parse JSON) memakai secret webhookmu.
3. Bandingkan dengan tanda tangan pada header memakai perbandingan waktu-konstan (constant-time compare) agar aman dari timing attack.
4. Kalau cocok, proses. Kalau tidak, balas 401 dan abaikan.

Satu hal penting saat tunneling: sebagian framework memodifikasi body sebelum kamu sempat membacanya mentah. Pastikan kamu membaca raw body sebelum middleware apa pun mem-parsingnya, karena tanda tangan dihitung atas byte asli. Kalau verifikasi selalu gagal padahal secret benar, penyebab paling umum adalah body yang sudah berubah.

Terapkan juga idempotensi: simpan reference_id yang sudah diproses agar webhook yang terkirim dua kali (karena retry) tidak menggandakan aksi bisnismu. Prinsip lengkapnya dibahas di webhook pembayaran.

Memicu Event Nyata dengan Mode Sandbox

Kamu tidak perlu uang sungguhan untuk menguji. Mode test tersedia sejak hari pertama. Alurnya:

1. Buat pembayaran dalam mode test (QRIS atau Virtual Account).
2. Selesaikan pembayaran memakai mekanisme simulasi sandbox.
3. Amati webhook payment.paid masuk ke endpoint lokalmu lewat tunnel.
4. Biarkan kode kedaluwarsa untuk menguji payment.expired.

Karena tunnel meneruskan request nyata dari sandbox, kamu menguji jalur yang sama persis dengan produksi, termasuk verifikasi tanda tangan. Panduan menyeluruh soal skenario uji ada di artikel uji pembayaran sandbox.

Menangani Retry saat Menguji

Saat men-debug, sengaja buat endpointmu membalas 500 untuk melihat bagaimana sistem menjadwalkan kirim ulang, lalu perbaiki dan amati apakah event yang sama datang lagi. Di sinilah idempotensi teruji: kalau kodemu benar, webhook berulang tidak akan menggandakan aksi. Panel inspeksi ngrok memudahkan ini karena kamu bisa mengulang request yang sama tanpa harus membuat transaksi baru setiap kali.

Kesalahan yang Sering Terjadi

Beberapa hambatan yang lazim saat pertama menyiapkan uji webhook lokal:

• Lupa memakai URL https. Selalu gunakan skema https dari tunnel, bukan http.
• URL tunnel berganti tiap sesi. ngrok dan cloudflared gratis memberi URL acak yang berubah setiap kali dijalankan ulang, jadi perbarui pendaftaran endpoint saat kamu memulai sesi baru.
• Verifikasi HMAC gagal karena body sudah di-parse. Pastikan raw body dibaca sebelum middleware JSON menyentuhnya.
• Endpoint lambat membalas. Kerjakan tugas berat secara asinkron dan balas 200 cepat agar tidak dianggap gagal.

Kesimpulan

Menguji webhook di komputer lokal tidak sulit begitu kamu paham dua bagiannya: tunneling untuk memberi localhost alamat publik, dan verifikasi HMAC untuk memastikan yang masuk memang sah. Gabungkan dengan mode sandbox untuk memicu event nyata tanpa risiko, dan gunakan panel inspeksi tunnel untuk mengulang request saat men-debug.

Mulai dari yang kecil: jalankan tunnel, daftarkan URL, verifikasi satu tanda tangan, lalu picu satu payment.paid. Setelah alur itu hijau, sisanya jauh lebih mudah. Baca dokumentasi untuk contoh header dan payload lengkap.