Masalah Nyata: Webhook Terkirim, Order Diproses Dua Kali

Pada integrasi payment gateway atau provider shipping, webhook adalah mekanisme umum untuk mengirim status transaksi ke aplikasi Laravel. Masalahnya, webhook tidak selalu datang satu kali. Provider bisa mengirim ulang event yang sama karena menganggap server kita tidak merespons tepat waktu, respons bukan HTTP 2xx, atau koneksi terputus di tengah jalan.

Studi kasus yang sering terjadi:

  • Payment gateway mengirim event payment.paid.
  • Controller Laravel langsung menjalankan proses berat: update order, kirim email, generate invoice, sinkron ke ERP.
  • Respons ke provider menjadi lambat, misalnya lebih dari 10 detik.
  • Provider menganggap webhook gagal dan melakukan retry.
  • Webhook kedua masuk saat proses pertama belum selesai atau baru selesai sebagian.
  • Akibatnya order ditandai lunas dua kali, stok berkurang dua kali, atau email terkirim berulang.

Kasus serupa juga sering muncul pada integrasi shipping, misalnya event shipment.delivered atau shipment.updated. Jika event status yang sama diproses berulang, histori pengiriman bisa berisi duplikasi, notifikasi terkirim dua kali, atau workflow internal maju terlalu cepat.

Inti masalahnya: endpoint webhook harus idempoten. Artinya, menerima event yang sama berkali-kali tetap menghasilkan efek akhir yang sama, bukan menjalankan side effect berulang.