---
title: Keamanan
description: Cara memvalidasi dan mengamankan payload webhook IDCloud — verifikasi tanda tangan dan praktik terbaik.
canonical: https://developer.unico.io/id/dual-api/developers/webhooks-and-events/security
locale: id
generated_by: markdown-export
---

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.

```javascript
// 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();
}
```

:::warning[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.