Stop Polling, Mulai Webhook: Notifikasi Transaksi Real-Time di IsiKuota

Kalau Anda masih melakukan polling berulang ke endpoint status hanya untuk tahu apakah transaksi sudah berhasil, ada cara yang jauh lebih efisien: webhook. Dengan webhook, IsiKuota yang akan memberitahu server Anda begitu status transaksi berubah.

Polling vs Webhook

	Polling	Webhook
Cara kerja	Anda terus bertanya "sudah selesai?"	IsiKuota memberi tahu saat selesai
Beban server	Boros request	Efisien
Kecepatan info	Terlambat (tergantung interval)	Real-time

Cara Kerja Webhook

Transaksi terjadi
       │ ▼
IsiKuota memproses
       │ ▼
Status berubah (success/failed)
       │ ▼
IsiKuota POST ke URL webhook Anda
       │ ▼
Server Anda balas HTTP 200

Contoh Payload

{
  "event": "transaction.updated",
  "event_id": "evt_01J3K8M2N4P5Q6R7S8T9U0V1W2",
  "timestamp": "2025-01-15T14:30:00+07:00",
  "data": {
    "ref_id": "ORDER-2025-001",
    "status": "success",
    "product_code": "TSEL5",
    "customer_no": "081234567890",
    "price": 11500,
    "sn": "1234567890123456",
    "balance": 489000
  }
}

Tentukan tindakan Anda berdasarkan data.status, bukan cuma dari nama event. Contoh di atas untuk transaction.updated (order PPOB) — ada juga event deposit.updated untuk notifikasi status deposit saldo via API, dikirim ke URL webhook yang sama. Detail struktur tiap event ada di Daftar Events.

WAJIB: Verifikasi Signature

Setiap request webhook menyertakan header X-Isikuota-Signature: sha256=<hex>. Selalu verifikasi sebelum memproses, untuk memastikan request benar-benar dari IsiKuota:

function verifyWebhook(string $rawBody, string $signature, string $secret): bool
{
    $expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);
    return hash_equals($expected, $signature);
}

Jangan skip verifikasi

Tanpa verifikasi signature, siapa pun bisa mengirim payload palsu ke endpoint Anda dan memicu pengiriman barang/saldo fiktif. Gunakan timing-safe comparison (hash_equals / timingSafeEqual).

Persyaratan Server

Persyaratan	Detail
Protokol	HTTPS (wajib di production)
Method	POST
Response	HTTP 2xx dalam 15 detik

Jika gagal, IsiKuota retry hingga 3 kali dengan jeda 10s, 30s, lalu 60s.

Best Practices

1. Verifikasi signature sebelum apa pun.
2. Balas HTTP 200 segera, proses di background/queue.
3. Idempoten — gunakan event_id atau ref_id untuk mendeteksi pengiriman ganda sebelum update database.
4. Log setiap callback untuk audit & debugging.
5. Test dulu dengan Webhook Tester di Dashboard.

Mulai Integrasi

1. Daftarkan URL webhook di Pengaturan → Webhook
2. Implementasikan verifikasi signature
3. Test dengan transaksi mode testing

→ Dokumentasi lengkap: Webhook Overview · Setup Webhook · Daftar Events.

---

Butuh bantuan? Lihat FAQ Developer & API atau hubungi [email protected].