Webhooks Aman: Verifikasi Signature, Cegah Replay, dan Tangani Retry

Webhook memungkinkan sebuah layanan mengirim notifikasi ke URL aplikasi ketika suatu peristiwa terjadi. Pola ini praktis untuk pembayaran, sinkronisasi data, dan otomasi. Karena endpoint sering dapat dijangkau dari internet, aplikasi perlu memastikan pesan benar-benar berasal dari pengirim yang sah dan tidak diproses berulang kali secara keliru.

Verifikasi signature dengan benar

Jika penyedia mendukung tanda tangan HMAC, verifikasi signature menggunakan secret yang disepakati dan payload mentah sesuai dokumentasi penyedia. Jangan mengubah spasi, urutan byte, atau encoding sebelum verifikasi jika algoritma mengharuskan payload asli. Bandingkan signature dengan fungsi perbandingan waktu-konstan yang tersedia di bahasa pemrograman.

Jangan hanya mempercayai alamat IP atau header yang mudah dipalsukan. Jika penyedia menyediakan tanda tangan asimetris, kunci publik, atau mekanisme autentikasi lain, ikuti dokumentasi resminya. Simpan secret di secret manager, rotasi bila bocor, dan hindari menampilkannya dalam log.

Cegah replay dan pemrosesan ganda

Signature yang valid tidak selalu membuktikan bahwa pesan baru. Jika penyedia menyertakan timestamp, periksa apakah waktunya berada dalam jendela yang masuk akal. Gunakan event ID atau identifier unik untuk menolak pemrosesan ulang. Batas waktu harus mempertimbangkan keterlambatan jaringan dan kebijakan retry penyedia.

Idempotensi penting karena pengirim dapat mengulangi webhook ketika respons tidak diterima. Simpan status pemrosesan event secara atomik agar dua permintaan serentak tidak menjalankan efek samping dua kali. Untuk pembayaran, jangan hanya mengandalkan tampilan sukses di browser; verifikasi status melalui mekanisme server-ke-server yang didukung penyedia.

Urutan pemrosesan yang disarankan

1. Terima permintaan dengan batas ukuran dan timeout yang masuk akal.
2. Verifikasi autentikasi atau signature sebelum mempercayai isi pesan.
3. Validasi timestamp, event ID, dan struktur data.
4. Simpan event ke antrean atau basis data secara aman.
5. Berikan respons sukses sesuai kontrak penyedia setelah pesan diterima untuk diproses.
6. Jalankan pekerjaan berat secara asinkron dan pantau kegagalan.

Jangan melakukan pekerjaan yang memakan waktu lama sebelum mengirim respons jika penyedia memiliki batas timeout ketat. Namun, jangan pula mengembalikan sukses sebelum event tersimpan dengan andal, karena pesan dapat hilang bila proses berhenti mendadak.

Retry, antrean, dan observabilitas

Retry perlu memiliki batas dan backoff agar gangguan sementara tidak menciptakan badai permintaan. Sediakan dead-letter queue atau mekanisme pemulihan untuk event yang terus gagal. Catat event ID, waktu, hasil verifikasi, latensi, dan status pemrosesan, tetapi hindari menyimpan data pribadi atau kredensial lengkap bila tidak diperlukan.

Uji skenario kegagalan

• Signature tidak valid atau header hilang.
• Timestamp terlalu lama atau berada di masa depan secara tidak wajar.
• Event ID yang sama dikirim dua kali atau secara bersamaan.
• Payload terlalu besar, tidak sesuai skema, atau berisi nilai tak terduga.
• Database atau antrean tidak tersedia sementara.
• Secret dirotasi dan pengirim masih menggunakan kunci lama selama masa transisi yang diizinkan.

Kesimpulan

Webhook yang aman membutuhkan lebih dari sekadar URL rahasia. Verifikasi signature, perlindungan replay, idempotensi, batas sumber daya, dan observabilitas harus dirancang bersama. Untuk memperkuat endpoint, baca juga panduan keamanan API dan HTTP security headers.