Apa Itu Webhook dan Mengapa Penting?
Webhook adalah mekanisme di mana server penyedia layanan (misalnya payment gateway) akan secara otomatis mengirimkan notifikasi HTTP ke URL yang Anda tentukan setiap kali terjadi event tertentu — seperti pembayaran berhasil, pembayaran gagal, atau refund diproses.
Berbeda dengan polling (di mana aplikasi Anda harus terus-menerus bertanya "Apakah ada update?"), webhook bersifat event-driven — lebih efisien, lebih cepat, dan tidak membuang resource server.
Cara Kerja Webhook Pembayaran
- Pelanggan melakukan pembayaran di platform Anda.
- Payment gateway memproses transaksi.
- Setelah status transaksi berubah (berhasil/gagal), payment gateway mengirimkan HTTP POST request ke webhook URL yang sudah Anda daftarkan.
- Server Anda menerima notifikasi, memverifikasi keasliannya, lalu memperbarui status pesanan di database.
- Server Anda merespons dengan HTTP 200 OK untuk mengonfirmasi notifikasi diterima.
Mendaftarkan Webhook URL
Setiap payment gateway memiliki cara berbeda untuk mendaftarkan webhook URL:
- Midtrans: Masuk ke dashboard → Settings → Configuration → Payment Notification URL. Midtrans mengirimkan notifikasi ke URL ini setiap kali status transaksi berubah.
- Xendit: Dashboard → Developers → Webhooks. Anda bisa mendaftarkan URL berbeda untuk event yang berbeda (invoice paid, payment received, dll.).
- DOKU: Konfigurasi melalui merchant portal, dengan menentukan notification URL di pengaturan integrasi.
Implementasi Endpoint Webhook (Contoh Konseptual)
Berikut adalah alur logika yang harus diimplementasikan di server Anda saat menerima webhook:
- Terima Request: Endpoint Anda harus dapat menerima HTTP POST dengan body berformat JSON.
- Verifikasi Signature: Selalu verifikasi bahwa request benar-benar berasal dari payment gateway, bukan dari pihak yang tidak sah. Caranya berbeda tiap gateway — biasanya menggunakan HMAC-SHA256 dari secret key Anda.
- Proses Event: Periksa field status transaksi di payload, lalu update database Anda sesuai status (success, pending, failed, expired).
- Kirim Response 200: Segera balas dengan HTTP 200 OK. Jika server Anda tidak merespons atau merespons dengan error, payment gateway biasanya akan retry pengiriman notifikasi beberapa kali.
Keamanan Webhook: Jangan Diabaikan
Karena webhook endpoint Anda adalah URL publik, ada risiko seseorang mengirimkan request palsu untuk memanipulasi status pesanan. Berikut praktik keamanan terbaik:
- Verifikasi Signature Selalu: Ini adalah garis pertahanan pertama dan paling penting.
- Validasi Data dengan Re-query: Setelah menerima notifikasi, lakukan re-query ke API payment gateway untuk mengkonfirmasi status transaksi secara independen.
- Gunakan HTTPS: Webhook endpoint Anda wajib menggunakan HTTPS, bukan HTTP.
- Whitelist IP: Jika payment gateway menyediakan daftar IP server mereka, whitelist IP tersebut di firewall Anda.
- Idempotency: Pastikan memproses event yang sama lebih dari sekali tidak menyebabkan duplikasi data. Simpan transaction ID dan cek apakah sudah diproses sebelumnya.
Menangani Retry dan Kegagalan
Payment gateway umumnya akan melakukan retry jika webhook Anda tidak merespons dengan 200 OK. Skenario yang perlu diantisipasi:
| Skenario | Penyebab | Solusi |
|---|---|---|
| Server timeout | Proses terlalu lambat | Terima webhook, proses secara async dengan queue |
| Database error | DB tidak tersedia | Return 500, biarkan gateway retry; pastikan HA database |
| Duplikat notifikasi | Retry dari gateway | Implementasi idempotency check berdasarkan transaction ID |
| Signature tidak valid | Konfigurasi salah / serangan | Log dan alert; jangan proses request |
Tips Debugging Webhook
- Gunakan tools seperti ngrok atau Webhook.site untuk menginspeksi payload webhook saat development di local environment.
- Log semua incoming webhook request (termasuk raw body) untuk keperluan debugging dan audit.
- Manfaatkan fitur "Resend Notification" di dashboard payment gateway saat testing.
Kesimpulan
Implementasi webhook yang benar adalah kunci untuk membangun sistem pembayaran yang andal, efisien, dan aman. Dengan memahami alur kerja, menerapkan verifikasi keamanan yang tepat, dan menangani edge case seperti retry dan duplikasi, aplikasi Anda akan siap menangani volume transaksi skala apapun.