Verifikasi Signature Webhook Pembayaran

Webhook adalah cara penyedia pembayaran memberi tahu sistem Anda bahwa sebuah transaksi berubah status: berhasil dibayar, gagal, atau dikembalikan. Karena webhook memicu aksi penting, seperti menandai pesanan lunas atau mengirim barang, ia menjadi target menggiurkan bagi pihak jahat. Bayangkan seseorang mengirim notifikasi palsu "pembayaran berhasil" ke endpoint Anda, lalu barang dikirim tanpa uang pernah masuk. Di sinilah verifikasi signature webhook menjadi benteng utama. Tanpa verifikasi, endpoint Anda pada dasarnya percaya pada siapa pun yang mengetuk pintu. Artikel ini menjelaskan cara memverifikasi signature webhook pembayaran secara benar, jujur, dan aman.

Mengapa Webhook Harus Diverifikasi

Endpoint webhook Anda biasanya terbuka ke internet agar penyedia bisa menjangkaunya. Sifat terbuka inilah yang membuatnya rentan. Jika Anda belum familier dengan konsep dasarnya, ulasan menyeluruh ada di webhook pembayaran.

Ancaman utama tanpa verifikasi:

• Notifikasi palsu — penyerang mengirim payload buatan yang mengaku dari penyedia.
• Manipulasi data — nilai transaksi atau status diubah di tengah jalan.
• Replay attack — notifikasi asli yang sah "diputar ulang" berkali-kali untuk memicu aksi ganda.

Verifikasi signature menjawab pertanyaan mendasar: benarkah pesan ini datang dari penyedia yang sah, dan apakah isinya utuh tidak diubah? Tanpa jawaban pasti untuk dua hal itu, seluruh alur pembayaran Anda berdiri di atas kepercayaan buta.

Yang membuat masalah ini serius adalah kesenjangan biaya antara penyerang dan korban. Mengirim ribuan notifikasi palsu ke endpoint terbuka nyaris tanpa biaya bagi penyerang, sementara satu saja yang lolos bisa berarti barang terkirim tanpa bayaran atau saldo tercatat keliru. Karena itu verifikasi bukan fitur opsional yang bisa "ditambahkan nanti", melainkan syarat dasar sebelum endpoint webhook boleh dipercaya sama sekali.

Cara Kerja Signature Berbasis HMAC

Metode paling umum adalah HMAC (Hash-based Message Authentication Code). Konsepnya sederhana namun kuat. Penyedia dan Anda sama-sama memegang sebuah secret rahasia. Saat mengirim webhook, penyedia menghitung "sidik jari" kriptografis dari isi pesan menggunakan secret tersebut, lalu menempelkannya di header (biasanya bernama seperti X-Signature).

Alur verifikasi di sisi Anda:

1. Terima payload mentah — ambil body request persis apa adanya, sebelum di-parse atau diubah.
2. Hitung ulang signature — gunakan secret yang sama untuk menghitung HMAC dari body mentah tersebut.
3. Bandingkan — cocokkan hasil hitungan Anda dengan nilai di header.
4. Terima atau tolak — jika sama persis, pesan sah; jika berbeda, tolak.

Karena penyerang tidak mengetahui secret, ia tidak bisa memalsukan signature yang cocok. Sedikit saja isi pesan diubah, signature akan berbeda total, sehingga manipulasi langsung ketahuan.

Kekuatan HMAC bertumpu sepenuhnya pada kerahasiaan secret. Selama secret hanya diketahui Anda dan penyedia, tidak ada pihak ketiga yang bisa menghasilkan signature valid, betapapun canggihnya mereka. Sebaliknya, jika secret sampai bocor, seluruh mekanisme runtuh seketika. Inilah alasan mengapa penyimpanan dan pengelolaan secret harus diperlakukan dengan kehati-hatian setingkat kunci brankas, bukan sekadar konstanta yang ditulis sembarangan di kode.

Detail Teknis yang Sering Terlewat

Banyak bug keamanan justru muncul dari detail kecil implementasi. Beberapa hal yang wajib diperhatikan:

• Gunakan body mentah — hitung signature dari raw body, bukan dari objek hasil parsing. Serialisasi ulang JSON bisa mengubah spasi atau urutan kunci, membuat hasil hitung tidak cocok padahal pesan sah.
• Perbandingan aman waktu (constant-time) — bandingkan signature dengan fungsi yang tahan terhadap timing attack, jangan sekadar == biasa.
• Jaga kerahasiaan secret — secret webhook harus diperlakukan sama ketatnya dengan kredensial lain, seperti dibahas pada keamanan API key.
• Cek timestamp untuk cegah replay — banyak penyedia menyertakan timestamp; tolak pesan yang terlalu lama untuk mempersempit peluang replay attack.

Kombinasi verifikasi signature dan pengecekan timestamp membuat endpoint Anda jauh lebih tangguh dibanding hanya mengandalkan salah satunya.

Idempotensi: Pertahanan Lapis Kedua

Verifikasi signature memastikan pesan sah dan utuh, tetapi ada satu skenario lagi yang perlu ditangani: penyedia yang sah bisa mengirim webhook yang sama lebih dari sekali, entah karena retry jaringan atau timeout. Jika sistem Anda memproses tiap pesan tanpa memeriksa apakah sudah pernah diproses, bisa terjadi aksi ganda seperti pesanan tercatat dua kali.

Solusinya adalah idempotensi: pastikan memproses pesan dengan ID yang sama dua kali menghasilkan efek yang sama seperti sekali. Praktik ini diuraikan pada idempotency API pembayaran. Cara umumnya adalah menyimpan ID event yang sudah diproses, lalu mengabaikan yang berulang. Ditambah lagi, endpoint webhook sebaiknya siap menghadapi kegagalan sesaat dan percobaan ulang, sebuah topik yang dibahas di menangani timeout retry. Signature menjaga keaslian, idempotensi menjaga konsistensi, dan keduanya saling melengkapi.

Perlu juga diperhatikan pola respons endpoint Anda. Kembalikan status sukses hanya setelah pesan benar-benar diterima dan dicatat, dan balas dengan cepat agar penyedia tidak menganggap pengiriman gagal lalu mengulang. Pekerjaan berat, seperti mengirim email atau memproses pesanan, sebaiknya dijalankan di belakang layar setelah respons dikirim. Dengan begitu, verifikasi, idempotensi, dan pola respons bekerja bersama membentuk endpoint webhook yang tangguh dari ujung ke ujung.

Praktik Terbaik dan Posisi yang Jujur

Ringkasan praktik terbaik verifikasi signature webhook:

• Selalu verifikasi setiap webhook — jangan pernah memproses payload yang belum lolos pemeriksaan signature.
• Tolak diam-diam pesan tidak sah — cukup kembalikan respons error tanpa membocorkan detail internal.
• Rotasi secret secara berkala — dan segera ganti jika dicurigai bocor.
• Log upaya yang gagal — untuk mendeteksi pola serangan lebih dini.

Perlu disampaikan secara jujur soal peran teknologi ini. BorderPay adalah lapisan teknologi (software) di atas mitra Payment Gateway yang berlisensi Bank Indonesia; pemrosesan dan penyimpanan dana dilakukan oleh mitra berlisensi. Sebagai lapisan perangkat lunak, BorderPay berupaya menyediakan pengalaman developer yang baik, termasuk mekanisme notifikasi dengan signature agar sistem Anda dapat memverifikasi keaslian pesan. Namun, tanggung jawab mengimplementasikan verifikasi di sisi penerima tetap ada pada Anda sebagai pemilik sistem.

Menutup: Jangan Percaya, Verifikasi

Prinsip keamanan webhook bisa diringkas dalam satu kalimat: jangan pernah percaya notifikasi yang belum diverifikasi. Signature berbasis HMAC memberi Anda kepastian bahwa pesan benar-benar berasal dari penyedia dan isinya tidak diubah, sementara pengecekan timestamp dan idempotensi menutup celah replay serta pemrosesan ganda. Investasi kecil untuk mengimplementasikan verifikasi ini jauh lebih murah daripada kerugian akibat transaksi palsu.

Jika Anda membangun integrasi pembayaran dan menginginkan lapisan teknologi yang mendukung praktik keamanan seperti ini di atas mitra berlisensi, BorderPay dapat menjadi fondasi yang membantu, selama Anda tetap menegakkan verifikasi di sisi sistem Anda sendiri.