Keamanan

Keandalan webhook bergantung pada perilaku endpoint Anda maupun jaminan pengiriman dari Unico. Halaman ini mencakup tiga invariant yang harus dipenuhi oleh endpoint Anda: idempotency, batas konkurensi, dan error rate.

Idempotency

Implementasi webhook Unico menjamin pengiriman setidaknya satu kali — status yang sama dapat diberitahukan lebih dari satu kali untuk processId yang sama. Endpoint Anda harus bersifat idempoten.

Pola yang direkomendasikan:

1. Pada setiap panggilan webhook, periksa terlebih dahulu apakah processId sudah diproses.
2. Jika sudah, kembalikan 2xx segera (pekerjaan sudah selesai).
3. Jika belum, terapkan logika bisnis Anda dan simpan fakta bahwa processId ini telah diproses.

// pseudo-code
async function handleWebhook(req, res) {
  const { processId } = req.body;

  if (await alreadyProcessed(processId)) {
    return res.status(200).end();
  }

  await applyBusinessLogic(req.body);
  await markAsProcessed(processId);
  return res.status(200).end();
}

Mengapa ini penting

Endpoint yang tidak idempoten dan menjalankan logika bisnis pada setiap pengiriman (misalnya, membebankan kartu, mengirim email) akan berjalan berulang kali ketika terjadi percobaan ulang — dan percobaan ulang adalah hal yang normal, bukan pengecualian, dalam pengiriman webhook.

Concurrency limit

Untuk melindungi endpoint Anda dari lonjakan selama periode volume tinggi, konfigurasikan jumlah maksimum pengiriman yang sedang berlangsung secara bersamaan (maks: 500) saat mendaftarkan webhook.

Ketika batas konkurensi tercapai, Unico mengantrekan pengiriman tambahan dan memprosesnya saat kapasitas tersedia. Dikombinasikan dengan percobaan ulang, hal ini berarti lonjakan yang berlanjut dapat memperpanjang waktu pengiriman efektif webhook baru.

Error rate

Error rate (respons di luar rentang 200–299) harus selalu rendah. Jika endpoint Anda mulai mengembalikan error dalam skala besar, Unico secara otomatis mengurangi throughput webhook untuk endpoint tersebut. Dikombinasikan dengan mekanisme percobaan ulang, ini dapat secara signifikan meningkatkan waktu eksekusi webhook baru.

Panduan operasional:

• Pantau respons non-2xx di sisi Anda. Beri peringatan pada error rate yang berkelanjutan di atas baseline normal Anda.
• Perlakukan handler webhook Anda sebagai jalur kritis — ini harus menjadi salah satu layanan yang paling andal dalam stack Anda.
• Untuk pemeliharaan terencana, lebih baik hentikan penerimaan di load balancer daripada mengembalikan 503. Respons non-2xx yang berkelanjutan — termasuk 503 — mengaktifkan pembatasan throughput otomatis yang dijelaskan di atas; ketika endpoint Anda pulih, throughput yang berkurang memperlambat pengiriman event yang mengantri selama gangguan. Jangan kembalikan 200 untuk event yang tidak diproses.

Semantik status

Perlakukan kumpulan nilai state dan lastEvent sebagai konfigurasi yang dapat berkembang:

• Hanya bereaksi terhadap status/event yang Anda tangani secara eksplisit.
• Catat nilai yang tidak dikenal — jangan mengeluarkan error untuk nilai tersebut.
• Status baru dapat ditambahkan tanpa perubahan versi mayor.