Webhook
Bisadagang mengirim POST dengan signature ke server Anda setiap ada perubahan, jadi Anda tidak perlu terus-menerus cek status.
Ringkasan
- Kami mengirim
POSTdengan body JSON ke URL HTTPS Anda. Setiap request diberi signature dengan HMAC-SHA256 memakai secretwhsec_…milik Anda. - Balas dengan status 2xx secepatnya (maksimal 10 detik), lalu proses di belakang. Selain 2xx, atau tidak ada balasan, kami kirim ulang sampai 8 percobaan.
- Event bisa datang lebih dari sekali. Simpan
event_iddan abaikan yang sudah pernah Anda terima. - Webhook sandbox dan production punya URL dan secret sendiri.
URL dan secret
Atur di dashboard, menu Webhook. Pilih environment (sandbox atau production), isi URL HTTPS lengkap, pilih event yang ingin diterima, lalu simpan.
- Hanya
https://. URL tanpa HTTPS ditolak saat disimpan. - Secret
whsec_…dibuat otomatis saat URL pertama disimpan, terpisah untuk setiap environment, dan terpisah dari API secret. Lihat dengan tombol Lihat, simpan di environment variable (mis.BISADAGANG_WEBHOOK_SECRET), jangan di kode atau commit. transaction.updatedselalu aktif. Event lain bisa dipilih.
Header
application/jsontransaction.updated.event_id di body. Tetap sama di setiap percobaan ulang.Event dan payload
Semua event memakai amplop yang sama. Field data berbeda menurut event.
production atau sandbox.Setiap event di bawah punya tabel field data dan contoh lengkap dengan amplopnya. Tipe | null berarti field selalu ada, nilainya bisa null. Anggap field baru bisa muncul kapan saja dan abaikan field yang tidak Anda kenal.
transaction.updated
data berisi pesanan seperti respons cek status. Cocokkan dengan ref_id Anda. Event pending dikirim paling banyak satu kali untuk satu rentang pending, lalu satu event lagi untuk status akhirnya (sukses atau gagal).
{
"event_id": "whd_7Hq2Xn4K",
"event": "transaction.updated",
"environment": "sandbox",
"created_at": "2026-11-19T03:15:42Z",
"data": {
"transaction_id": "PL1763522142AB12",
"ref_id": "INV-20261119-0001",
"product_code": "TSEL10",
"customer_no": "081200000001",
"price": 10450,
"status": "success",
"sn": "1234567890123456",
"message": null
}
}complaint.updated
Dikirim saat status komplain berubah atau tim membalas. Balasan dan komplain yang Anda kirim sendiri tidak memicu event. Lihat API Komplain.
{
"event_id": "whd_Rk3Lm9Pa",
"event": "complaint.updated",
"environment": "production",
"created_at": "2026-11-19T05:41:13Z",
"data": {
"complaint_id": "KMP1763527331A1K7",
"transaction_id": "PL1763522142AB12",
"ref_id": "INV-20261119-0001",
"status": "resolved",
"result": "success",
"message": {
"from": "system",
"text": "Komplain selesai. Transaksi berstatus sukses.",
"created_at": "2026-11-19T05:41:13.000Z"
}
}
}product.auto_disabled
Hanya production. Dikirim saat success rate 24 jam sebuah produk turun di bawah batas Anda dan jumlah transaksi minimalnya terpenuhi. Produknya langsung nonaktif untuk akun Anda.
{
"event_id": "whd_Tz8Vb2Qe",
"event": "product.auto_disabled",
"environment": "production",
"created_at": "2026-11-19T06:10:00Z",
"data": {
"product_code": "AXIS10",
"product_name": "Axis 10.000",
"category": "Pulsa",
"success_rate": 71.2,
"threshold": 90,
"transactions": 38,
"min_transactions": 20,
"disabled_at": "2026-11-19T06:10:00Z"
}
}product.auto_enabled
Hanya production. Dikirim saat produk yang dinonaktifkan otomatis pulih di atas batas dan aktif lagi. Produk yang Anda nonaktifkan sendiri tidak diaktifkan lagi dan tidak memicu event.
Aturan aktif lagi: produk sudah nonaktif minimal 1 jam, lalu success rate 24 jam mencapai batas Anda ditambah 5 poin (maksimal 100). Jika selama 24 jam tidak ada cukup transaksi final untuk dinilai (kurang dari minimal Anda), produk diaktifkan lagi dan success_rate bernilai 0. Jika Anda mematikan aturan nonaktif otomatis, produk yang tertahan aktif lagi tanpa event ini. Produk yang Anda aktifkan sendiri setelah dinonaktifkan otomatis dikecualikan dari nonaktif otomatis selama 1 jam.
{
"event_id": "whd_Ym4Ns7Cw",
"event": "product.auto_enabled",
"environment": "production",
"created_at": "2026-11-19T09:35:00Z",
"data": {
"product_code": "AXIS10",
"product_name": "Axis 10.000",
"category": "Pulsa",
"success_rate": 94.5,
"threshold": 90,
"enabled_at": "2026-11-19T09:35:00Z"
}
}product.created
Satu event untuk satu kali produk baru masuk katalog, bisa berisi beberapa produk. Field produk sama dengan daftar produk, ditambah active.
{
"event_id": "whd_Df6Hj1Kx",
"event": "product.created",
"environment": "production",
"created_at": "2026-11-19T07:00:00Z",
"data": {
"total": 2,
"products": [
{
"code": "TSEL15",
"product_name": "Telkomsel 15.000",
"category": "Pulsa",
"brand": "TELKOMSEL",
"type": "Umum",
"product_type": "prepaid",
"is_open_amount": false,
"status": "normal",
"price": 15420,
"fee": null,
"admin_fee": null,
"commission": null,
"active": false
},
{
"code": "BPJSKES",
"product_name": "BPJS Kesehatan",
"category": "Pascabayar",
"brand": "BPJS KESEHATAN",
"type": "Umum",
"product_type": "postpaid",
"is_open_amount": false,
"status": "normal",
"price": null,
"fee": null,
"admin_fee": 2500,
"commission": 800,
"active": true
}
]
}
}price.changed
Satu event untuk satu kali pembaruan harga, bisa berisi beberapa produk. Hanya produk yang aktif untuk akun Anda yang dilaporkan, dan hanya field yang berubah di changes.
{
"event_id": "whd_Lp9Wc3Rd",
"event": "price.changed",
"environment": "production",
"created_at": "2026-11-19T08:00:00Z",
"data": {
"total": 3,
"products": [
{
"code": "TSEL10",
"product_name": "Telkomsel 10.000",
"product_type": "prepaid",
"changes": {
"price": {
"old": 10450,
"new": 10520
}
}
},
{
"code": "TFBCA",
"product_name": "Transfer Bank BCA",
"product_type": "prepaid",
"changes": {
"fee": {
"old": 2500,
"new": 3000
}
}
},
{
"code": "PLNPASCA",
"product_name": "PLN Pascabayar",
"product_type": "postpaid",
"changes": {
"admin_fee": {
"old": 2750,
"new": 3000
},
"commission": {
"old": 1200,
"new": 1100
}
}
}
]
}
}balance.low
Hanya production. Dikirim sekali saat saldo turun di bawah batas peringatan Anda (atur di dashboard, menu Saldo), dan baru dikirim lagi setelah saldo naik di atas batas lalu turun lagi.
{
"event_id": "whd_Gu5Xa8Ne",
"event": "balance.low",
"environment": "production",
"created_at": "2026-11-19T10:22:00Z",
"data": {
"balance": 480000,
"threshold": 500000,
"currency": "IDR"
}
}Verifikasi signature
Selalu verifikasi sebelum memproses. Tanpa ini siapa pun yang tahu URL Anda bisa mengirim status palsu.
- Ambil body mentah persis seperti diterima, sebelum di-parse menjadi JSON.
- Susun teks
timestamp + "." + body, dengantimestampdari headerX-Bisadagang-Timestamp. - Hitung HMAC-SHA256 dengan seluruh secret
whsec_…sebagai kunci, hasilnya hex huruf kecil. - Bandingkan dengan header
X-Bisadagang-Signaturesecara constant-time. - Tolak jika timestamp lebih dari 300 detik dari jam server Anda (mencegah request lama dipakai ulang).
Contoh uji
Pakai nilai tetap ini untuk memastikan fungsi Anda benar. Secret ini hanya contoh dan tidak pernah dipakai.
whsec_contoh_rahasia_jangan_dipakai176352214216587d07452dff66f95860bd51f9cc322d41cbe5b31e89ad9c9fea3f58277ef2Contoh kode
import { createHmac, timingSafeEqual } from 'node:crypto';
// true jika salah satu signature di header cocok (dua signature dipisah koma saat rotasi secret)
export function verifySignature(secret, timestamp, rawBody, signatureHeader) {
const expected = createHmac('sha256', secret)
.update(`${timestamp}.${rawBody}`)
.digest('hex');
return String(signatureHeader)
.split(',')
.some(sig => {
const given = Buffer.from(sig.trim(), 'hex');
const want = Buffer.from(expected, 'hex');
return given.length === want.length && timingSafeEqual(given, want);
});
}
import express from 'express';
const app = express();
// Pakai body mentah. Jangan verifikasi hasil JSON.parse, karena susunan teksnya bisa berubah.
app.post('/webhooks/bisadagang', express.raw({ type: 'application/json' }), (req, res) => {
const rawBody = req.body.toString('utf8');
const timestamp = req.get('X-Bisadagang-Timestamp');
const signature = req.get('X-Bisadagang-Signature');
const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) <= 300;
const valid = verifySignature(process.env.BISADAGANG_WEBHOOK_SECRET, timestamp, rawBody, signature);
if (!fresh || !valid) return res.sendStatus(401);
const event = JSON.parse(rawBody);
// Simpan event.event_id dengan aturan unik. Jika sudah ada, abaikan (event duplikat).
// Proses di belakang (antrean atau worker), jangan di sini.
res.sendStatus(200);
});
app.listen(3000);Contoh JavaScript untuk Node.js 18 ke atas dengan Express, contoh Python dengan Flask. Fungsi verifikasinya (verifySignature, verify_signature di Python) diuji dengan nilai contoh di atas.
Cara membalas
- Balas 2xx (biasanya
200) tanpa menunggu pekerjaan selesai. Body balasan tidak dipakai. - Simpan event ke database atau antrean, balas, lalu proses di worker. Proses yang lambat di dalam handler membuat kami menunggu, lalu menganggap gagal setelah 10 detik.
- Signature salah atau timestamp lebih dari 300 detik dari jam server Anda: balas
401. Jangan balas 2xx untuk request yang tidak lolos verifikasi. - Balasan
3xxtidak diikuti dan dihitung gagal. Daftarkan URL akhir.
Jadwal kirim ulang
Pengiriman dianggap berhasil hanya jika server Anda membalas 2xx. Jika tidak, kami mencoba lagi dengan jeda yang makin panjang, total 8 percobaan dalam sekitar 24 jam. Waktu di bawah adalah perkiraan, dihitung dari event dibuat.
Setelah percobaan ke-8gagal, kami berhenti dan menampilkan peringatan di dashboard (dan email jika notifikasi “webhook gagal” aktif). Event itu tetap ada di log selama 30 hari dan bisa dikirim ulang manual.
Idempotensi
- Satu event bisa tiba lebih dari sekali: percobaan ulang setelah balasan Anda terlambat, atau kirim ulang manual. Semuanya membawa
event_idyang sama. - Simpan
event_iddengan aturan unik. Jika sudah ada, balas200dan lewati. - Satu transaksi bisa menghasilkan beberapa event (pending paling banyak sekali per rentang pending, lalu status akhir) dengan
event_idberbeda, dan urutan tiba tidak dijamin. Gunakandata.statusdancreated_at, dan jangan menurunkan transaksi yang sudah final.
Kirim tes dan log
- Kirim tes di dashboard mengirim satu event bernama
webhook.test, bertanda tangan, ke URL environment yang dipilih, lalu menampilkan kode balasan dan lamanya. Balas 2xx seperti event biasa. Event tes tidak masuk log pengiriman dan tidak dikirim ulang. Isidata-nya selalu{ "message": "Tes webhook dari Bisadagang Bisnis." }; abaikan setelah signature lolos. - Log pengiriman menyimpan 30 hari terakhir: filter Gagal dan per event, detail request (header, body) dan balasan server Anda (dipotong 2 KB), serta semua percobaan.
- Kirim ulang menambah satu percobaan dengan ID pengiriman yang sama, dari log atau dari halaman detail transaksi.
- Di sandbox, nomor tujuan skenario (lihat Sandbox) memicu event sungguhan ke URL sandbox Anda.
Rotasi secret
Rotasi di dashboard jika secret bocor atau orang yang tahu sudah keluar. Mulai saat itu webhook diberi signature dengan secret baru; secret lama tetap berlaku 24 jam lagi. Selama itu header X-Bisadagang-Signature membawa dua signature dipisah koma, dan contoh kode di atas menerima salah satunya. Perbarui environment variable di server Anda dalam jangka waktu tersebut.