Payment Gateway Idempotent Webhook Handler

1. Studi Kasus

Payment gateway mengirimkan webhook event (payment.success) untuk memperbarui status transaksi di database Anda. Karena kegagalan jaringan, payment gateway sering melakukan retry webhook yang sama berkali-kali. API Anda harus menjamin Idempotency (event ID yang sama tidak boleh diproses 2 kali) dan memverifikasi Signature Webhook.

Endpoint:

POST /webhook/payment

---

2. Spesifikasi Input & Output

Header:

x-signature: VALID_SIGNATURE_KEY

Request Body:

{
  "eventId": "EVT_998811",
  "orderId": "ORD_1001",
  "status": "SUCCESS",
  "amount": 250000
}

---

3. Data Awal In-Memory

const processedEventIds = new Set();
const orders = [
  { orderId: "ORD_1001", status: "PENDING_PAYMENT", amount: 250000 }
];

---

4. Aturan Validasi & Requirement

1. Verifikasi Signature: Jika header x-signature !== "VALID_SIGNATURE_KEY" → HTTP 401 "Unauthorized webhook signature".
2. Validasi Payload: Jika eventId, orderId, atau status kosong → HTTP 400 "Invalid webhook payload".
3. Cek Duplikasi Event (Idempotency): Jika processedEventIds.has(eventId) → HTTP 200 "Event already processed". (Penting: Tetap kembalikan HTTP 200 agar payment gateway tidak retry terus menerus!).
4. Update Status Order: Cari order berdasarkan orderId. Ubah order.status = status dan masukkan eventId ke processedEventIds. Kembalikan HTTP 200 "Order updated successfully".

---

5. Pertanyaan Bonus Konseptual 💡

Strategi Webhook Dead Letter Queue (DLQ) & Exponential Backoff Di bagian komentar kode solusi Anda, jelaskan penanganan kegagalan webhook pihak ketiga menggunakan Message Queue (BullMQ/Kafka), Dead Letter Queue (DLQ), dan Retry backoff (1s, 5s, 30s, 5m).