Webhook yang andal: retry, tanda tangan, dan idempotensi

Prinsip dasar penerima webhook

Balas dengan status 200 secepat mungkin, lalu proses pekerjaan berat di antrean latar belakang. Pengirim umumnya menganggap gagal bila tidak ada balasan dalam beberapa detik.

• Verifikasi tanda tangan HMAC dengan rahasia bersama sebelum memercayai isi.
• Simpan event mentah lebih dulu agar bisa diputar ulang saat ada bug.
• Tolak payload yang stempel waktunya terlalu lama untuk mencegah serangan replay.
• Catat ID event untuk deduplikasi.

Idempotensi: aman diproses berulang

Idempotensi berarti hasil akhir sama walau event yang sama diproses dua kali. Simpan ID event unik di tabel dengan batasan unik. Bila insert gagal karena duplikat, lewati pemrosesan.

Untuk operasi seperti menandai pesanan lunas, gunakan pembaruan kondisional (hanya jika status masih menunggu pembayaran) agar tidak menimpa status yang lebih baru.

Retry dan pemantauan

Sebagai pengirim, gunakan retry dengan exponential backoff, misalnya 1 menit, 5 menit, 30 menit, lalu 2 jam, dan sediakan dead-letter queue untuk event yang tetap gagal.

Pasang peringatan bila rasio kegagalan melebihi ambang tertentu dan sediakan dasbor riwayat pengiriman agar tim dukungan bisa menelusuri masalah tanpa membuka basis data.

Daftar periksa penerima webhook

Sebelum webhook dipakai di produksi, pastikan setiap butir berikut terpenuhi.

• Membalas status 2xx dalam waktu kurang dari beberapa detik.
• Tanda tangan diverifikasi dengan rahasia yang disimpan aman.
• ID event disimpan dengan batasan unik di database.
• Pemrosesan berat dipindah ke antrean latar belakang.
• Ada peringatan bila rasio gagal naik.

Webhook yang dirancang dengan benar membuat integrasi pembayaran, pengiriman, dan CRM berjalan stabil tanpa campur tangan manual setiap kali ada gangguan jaringan.

Kesalahan yang perlu dihindari

Kesalahan paling umum adalah memproses semua pekerjaan di dalam handler sehingga permintaan kehabisan waktu dan pengirim terus mengulang. Kesalahan lain adalah tidak memverifikasi tanda tangan sehingga siapa pun bisa memalsukan event.

Hindari juga mengandalkan urutan kedatangan event. Selalu periksa status terkini sebelum menerapkan perubahan agar event terlambat tidak menimpa data yang lebih baru.