Webhook Aman: Cara Memvalidasi Signature dan Mencegah Pemrosesan Ganda

Webhook memungkinkan dua aplikasi saling memberi tahu ketika sebuah peristiwa terjadi. Misalnya, layanan pembayaran mengirim notifikasi setelah status transaksi berubah, atau platform proyek memberi tahu aplikasi lain ketika tugas diperbarui. Penerima tidak perlu terus-menerus meminta pembaruan ke layanan sumber. Namun, karena webhook biasanya diterima melalui endpoint jaringan, aplikasi harus memastikan pesan benar-benar berasal dari penyedia yang sah dan tidak memproses peristiwa yang sama berulang kali.

Apa itu webhook dan apa risikonya?

Webhook adalah permintaan HTTP yang dikirim otomatis ke URL penerima ketika peristiwa tertentu terjadi. Pesannya dapat berisi identitas peristiwa, waktu, objek yang berubah, serta data yang dibutuhkan aplikasi. Implementasi yang hanya menerima JSON tanpa autentikasi berisiko memproses pesan palsu. Sementara itu, penyedia dapat mengirim ulang notifikasi ketika server penerima terlambat merespons atau koneksi terputus. Karena itu, validasi keaslian dan penanganan duplikasi harus dirancang bersama.

Gunakan HTTPS dan endpoint khusus

Pasang endpoint webhook pada HTTPS agar lalu lintas dienkripsi saat transit dan klien dapat memverifikasi server penerima. Sediakan rute khusus, batasi metode HTTP yang diterima, dan tetapkan ukuran maksimum permintaan serta batas waktu pemrosesan. Respons kesalahan sebaiknya tidak membocorkan token, rahasia, atau detail internal. Jika penyedia menyediakan daftar alamat IP sumber yang stabil, aturan jaringan dapat menjadi lapisan tambahan, tetapi daftar IP bukan pengganti validasi signature dan perlu diperbarui saat infrastrukturnya berubah.

Validasi signature dengan benar

Banyak penyedia webhook menyertakan signature kriptografis pada header. Penerima menghitung nilai yang diharapkan menggunakan isi pesan dan rahasia bersama, lalu membandingkannya dengan signature yang diterima. Ikuti dokumentasi penyedia mengenai algoritme, format header, encoding, dan apakah timestamp ikut ditandatangani. Jika pustaka resmi tersedia, gunakan pustaka tersebut daripada membuat algoritme sendiri.

Hal penting lainnya adalah memvalidasi byte tubuh permintaan yang asli jika itulah yang digunakan penyedia untuk membuat signature. Mengurai JSON lalu menyusunnya kembali dapat mengubah spasi, urutan representasi, atau encoding sehingga hasil perhitungan berbeda. Jangan menerima pesan hanya karena header signature ada; perhitungan dan pemeriksaan harus benar-benar berhasil.

Gunakan perbandingan signature yang aman terhadap perbedaan waktu eksekusi, sesuai kemampuan bahasa atau pustaka yang dipakai. Simpan rahasia di secret manager atau konfigurasi server dengan akses terbatas, bukan di kode sumber, repositori, maupun log. Siapkan proses rotasi jika rahasia diduga bocor. Jika penyedia mendukung beberapa secret selama masa rotasi, ikuti prosedur resminya agar pergantian tidak membuat integrasi terputus.

Periksa timestamp dan cegah replay

Signature yang valid membuktikan bahwa pesan dibuat oleh pihak yang mengetahui rahasia, tetapi tidak selalu membuktikan bahwa pesan itu baru. Penyerang yang memperoleh salinan permintaan lama mungkin mencoba mengirimkannya kembali. Jika penyedia menyertakan timestamp atau nomor urut, verifikasi sesuai spesifikasinya dan tolak pesan yang berada di luar jendela waktu yang diizinkan. Jangan membuat aturan waktu sendiri tanpa memeriksa toleransi resmi penyedia, karena perbedaan jam server dapat menyebabkan pesan sah ditolak.

Untuk perlindungan tambahan, simpan identitas peristiwa atau ID pengiriman yang unik. Sebelum memproses pesan, periksa apakah ID tersebut sudah pernah diterima. Simpan catatan idempotensi secara atomik di penyimpanan yang sesuai, dengan indeks unik atau mekanisme transaksi agar dua permintaan bersamaan tidak lolos pemeriksaan sekaligus.

Terapkan idempotensi untuk mencegah pemrosesan ganda

Operasi disebut idempoten jika pengulangan permintaan yang sama tidak menggandakan efek akhirnya. Contohnya, sistem pembayaran tidak boleh menambahkan saldo dua kali hanya karena notifikasi transaksi yang sama dikirim ulang. Gunakan ID peristiwa dari penyedia sebagai kunci idempotensi jika tersedia. Catat status pemrosesan dan hasilnya, lalu pastikan perubahan data bisnis dan penandaan peristiwa diperlakukan secara konsisten. Jika pekerjaan panjang dilakukan melalui antrean, tandai pesan dengan status yang jelas dan buat pekerja aman terhadap pengiriman ulang.

Hindari pola sederhana “periksa ID, lalu simpan ID” tanpa perlindungan konkurensi. Dua worker dapat memeriksa pada saat hampir bersamaan dan keduanya menganggap pesan belum pernah diproses. Kendala unik di basis data atau transaksi atomik membantu menutup celah tersebut. Tentukan juga masa retensi ID berdasarkan kebijakan pengiriman ulang penyedia dan kebutuhan bisnis.

Respons, log, dan pemantauan

Respons HTTP sebaiknya mengikuti panduan penyedia. Umumnya, penerima perlu memberi respons sukses setelah pesan diterima dengan aman untuk diproses, bukan menunggu semua pekerjaan latar belakang selesai. Namun, jangan mengirim respons sukses sebelum pesan tersimpan secara andal, karena kegagalan sesudahnya dapat membuat peristiwa hilang. Untuk proses yang berat, simpan pesan ke antrean terlebih dahulu lalu kerjakan secara asinkron.

Catat waktu penerimaan, ID peristiwa, hasil validasi, durasi pemrosesan, dan jenis kesalahan. Hindari mencatat secret, token, data pembayaran, atau seluruh payload jika tidak diperlukan. Pantau lonjakan signature tidak valid, banyaknya pengiriman ulang, antrean yang menumpuk, dan kegagalan pemrosesan. Uji skenario pesan palsu, signature salah, timestamp kedaluwarsa, ID duplikat, serta dua pengiriman bersamaan di lingkungan pengujian.

Daftar pemeriksaan sebelum digunakan

• Endpoint hanya menerima metode dan ukuran permintaan yang diperlukan.
• Signature dihitung mengikuti dokumentasi penyedia dan isi permintaan asli.
• Timestamp atau perlindungan replay diperiksa jika didukung.
• ID peristiwa disimpan dengan mekanisme idempotensi yang aman terhadap konkurensi.
• Secret disimpan secara aman dan memiliki prosedur rotasi.
• Log tidak memuat kredensial atau data sensitif yang tidak diperlukan.
• Pengiriman ulang, kegagalan jaringan, dan pemrosesan paralel telah diuji.

Kesimpulan

Webhook yang aman membutuhkan lebih dari sekadar endpoint HTTPS. Validasi signature membantu memeriksa keaslian pesan, pemeriksaan timestamp dapat membatasi replay, dan idempotensi mencegah efek bisnis terjadi berkali-kali akibat pengiriman ulang. Gabungkan kontrol tersebut dengan penyimpanan yang andal, log yang tidak membocorkan rahasia, serta pengujian kegagalan. Selalu ikuti dokumentasi resmi penyedia webhook karena format signature, header, dan kebijakan retry berbeda-beda.

Referensi: GitHub Docs: Validating webhook deliveries dan Stripe Docs: Webhooks.