Skip to main content
Daftarkan URL HTTPS di Dashboard → Pengaturan → Developer API, pilih event, lalu simpan signing secret (ditampilkan sekali). Produksi wajib HTTPS. http://localhost dan http://127.0.0.1 diizinkan untuk development. Webhook tersedia di paket Growth dan Scale, bersama Public API. Spec payload per event ada di sidebar Webhook Events.

Event

Tidak ada status cancelled atau completed. Gunakan order.expired / order.failed dan order.paid. Saat status menjadi paid, Anda menerima dua delivery jika keduanya dipilih: order.updated dan order.paid. Proses masing-masing secara idempoten. Return URL payment gateway bukan bukti lunas — pembeli bisa kembali ke redirect.return_url saat status masih pending. Grant akses hanya setelah order.paid (atau GET order status: paid).

Request

Setiap delivery adalah POST JSON. User-Agent: KawanDigital-Webhooks/1.0.

Headers

Body

id di body adalah ID event. Objek data.order sama dengan response GET /v1/orders/{order_id}. payment_url hanya ada selama pembayaran masih diperlukan (pending / awaiting_verification).

Verifikasi signature

Payload yang ditandatangani: {timestamp}.{raw_body} (body mentah, bukan JSON yang di-parse ulang). HMAC-SHA256, output hex, memakai signing secret webhook. Tolak jika timestamp lebih dari 300 detik dari waktu server Anda. Baca body sebagai raw bytes/string sebelum JSON.parse. Parsing lalu stringify ulang akan mengubah whitespace dan gagal verifikasi.

Node.js

PHP

Idempotensi

Simpan X-Kawan-Delivery-Id (atau id di body) yang sudah diproses. Delivery yang sama bisa dikirim ulang setelah timeout, retry, atau tombol retry di dashboard. Jangan anggap order.id unik per event — satu order memicu banyak event.

Response & retry

  • Timeout: 10 detik.
  • Sukses: HTTP 2xx. Balas cepat, kerjakan job berat di antrian Anda.
  • Di-retry: error jaringan, 408, 429, 5xx. Backoff 30s × 2^(attempts-1), maksimum 1 jam, maksimal 5 percobaan.
  • 4xx lain (termasuk 401 dari signature yang salah) tidak di-retry.
  • Delivery gagal bisa di-retry manual dari dashboard.
Worker berjalan lewat cron setiap 2 menit. Jangan mengandalkan webhook untuk menyelesaikan checkout pembeli.

Lanjut