Webhook Guide
Cara menerima notifikasi otomatis dari Bukasir saat status transaksi berubah.
Cara Kerja Webhook
Ketika status transaksi berubah, Midtrans mengirimkan notifikasi ke Bukasir. Bukasir memverifikasi signature (SHA512) dari Midtrans, mencocokkan nominal dengan database, mengonfirmasi ulang ke Midtrans Status API sebelum status completed, lalu memperbarui status transaksi di database. Setelah itu, Bukasir me-relay notifikasi ke webhook URL yang sudah Anda daftarkan.
Alur lengkap:
- Midtrans mengirim POST notification ke Bukasir (
/api/webhook) - Bukasir memverifikasi signature Midtrans (SHA512)
- Bukasir mencocokkan
gross_amountdenganamount + feedi database — tidak cocok = ditolak - Sebelum
completed, Bukasir mengonfirmasi ulang via Midtrans Status API (wajib di mode live) - Bukasir memperbarui status transaksi di database (mapping status Midtrans ke status platform)
- Bukasir me-relay notifikasi ke
webhook_urlmerchant Anda, ditandatangani HMAC-SHA256 per project - Field
signature_keydihapus dari payload,order_iddikembalikan ke order_id merchant Anda, selain itu dikirim apa adanya
signature_key yang dihapus).
Setup Webhook
- Login ke dashboard Bukasir
- Buka Pengaturan > Profil
- Isi field Webhook URL (contoh:
https://yourdomain.com/webhook) - Klik Simpan
Verifikasi Webhook (Wajib)
Setiap webhook request dari Bukasir membawa header X-Bukasir-Signature berisi HMAC-SHA256 dari body mentah, dihitung dengan webhook secret per project (lihat Dashboard > Projects > Edit), plus header X-Bukasir-Timestamp (unix epoch).
Format signature: sha256=hex(HMAC_SHA256(secret, timestamp + "." + raw_body)). Timestamp yang lebih tua dari 5 menit wajib ditolak (anti replay). Header lama X-Bukasir-Webhook: 1 masih dikirim untuk kompatibilitas, tetapi bukan bukti autentikasi — jangan verifikasi hanya dengan header itu.
Setelah signature valid, wajib rekonsiliasi via GET /api/status/{order_id} (pakai API key Anda): pastikan order ada, amount + fee cocok, dan status sudah completed sebelum memproses pesanan.
PHP
<?php
// Ambil body MENTAH (jangan json_encode ulang — merusak signature)
$rawBody = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_BUKASIR_SIGNATURE'] ?? '';
$timestamp = $_SERVER['HTTP_X_BUKASIR_TIMESTAMP'] ?? '';
$secret = 'ISI_WEBHOOK_SECRET_DARI_DASHBOARD';
// 1. Tolak timestamp basi (> 5 menit) — anti replay
if (!ctype_digit($timestamp) || abs(time() - (int) $timestamp) > 300) {
http_response_code(403);
die('Stale timestamp');
}
// 2. Verifikasi HMAC (timing-safe)
$expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
if (!hash_equals($expected, strtolower(trim($signature)))) {
http_response_code(403);
die('Invalid signature');
}
$data = json_decode($rawBody, true);
$orderId = $data['order_id'] ?? '';
// 3. Rekonsiliasi ke Bukasir sebelum proses pesanan
$ch = curl_init('https://bukasir.biz.id/api/status/' . urlencode($orderId));
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['X-API-Key: ISI_API_KEY_ANDA'],
CURLOPT_TIMEOUT => 15,
]);
$statusRes = json_decode(curl_exec($ch), true);
curl_close($ch);
if (($statusRes['status'] ?? '') !== 'completed') {
http_response_code(200); // terima webhook, tapi jangan proses pesanan
die('Belum lunas menurut /api/status');
}
// 4. Cocokkan nominal dengan order di database Anda, lalu proses
// if ((float) $statusRes['amount'] + (float) $statusRes['fee'] !== $orderDbTotal) die('Nominal beda');
http_response_code(200);
echo json_encode(['success' => true]);
?>
Node.js / Express
const crypto = require('crypto');
const SECRET = process.env.BUKASIR_WEBHOOK_SECRET; // dari dashboard
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
const rawBody = req.body.toString('utf8'); // body mentah!
const signature = req.headers['x-bukasir-signature'] || '';
const timestamp = req.headers['x-bukasir-timestamp'] || '';
if (!/^\d+$/.test(timestamp) || Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
return res.status(403).json({ error: 'Stale timestamp' });
}
const expected = 'sha256=' + crypto
.createHmac('sha256', SECRET)
.update(timestamp + '.' + rawBody)
.digest('hex');
if (signature.length !== expected.length ||
!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
return res.status(403).json({ error: 'Invalid signature' });
}
const { order_id } = JSON.parse(rawBody);
// TODO: GET /api/status/:order_id dengan X-API-Key, cek completed + nominal, baru proses
res.json({ success: true });
});
Payload Format
Payload yang dikirimkan adalah notifikasi asli dari Midtrans (tanpa field signature_key). Berikut contoh payload yang akan Anda terima:
{
"transaction_time": "2026-07-23 14:30:00",
"transaction_status": "settlement",
"transaction_id": "abc123-def456-ghi789",
"status_code": "200",
"order_id": "ORDER-001",
"gross_amount": "50350.00",
"payment_type": "qris",
"fraud_status": "accept",
"settlement_time": "2026-07-23 14:30:15"
}
Field Deskripsi
| Field | Type | Deskripsi |
|---|---|---|
order_id |
string | Unique identifier transaksi |
transaction_status |
string | Status transaksi dari Midtrans (bukan status platform Bukasir) |
transaction_id |
string | ID transaksi dari Midtrans |
status_code |
string | HTTP-like status code dari Midtrans (misal "200") |
gross_amount |
string | Total yang dibayarkan, format string desimal (misal "50350.00") |
payment_type |
string | Metode pembayaran: qris, bank_transfer, gopay, dll. |
fraud_status |
string | Status fraud: accept, challenge, deny |
transaction_time |
string | Waktu transaksi dibuat (format: YYYY-MM-DD HH:MM:SS) |
settlement_time |
string | Waktu pembayaran diselesaikan (format: YYYY-MM-DD HH:MM:SS) |
Status Pembayaran
Webhook meneruskan status dari Midtrans (transaction_status). Perhatikan bahwa ini berbeda dari status platform Bukasir (completed, expired, cancelled, failed).
| Status Midtrans | Deskripsi | Aksi yang Disarankan |
|---|---|---|
pending |
Menunggu pembayaran dari customer | Tunggu — jangan proses pesanan |
capture |
Transaksi berhasil di-capture (kartu kredit) | Cek fraud_status sebelum proses |
settlement |
Pembayaran berhasil diterima | Proses pesanan / kirim barang |
expire |
Pembayaran melewati batas waktu | Batalkan pesanan / informasikan ke customer |
cancel |
Transaksi dibatalkan | Tidak perlu aksi tambahan |
deny |
Pembayaran ditolak oleh provider | Hubungi customer untuk pembayaran ulang |
refund |
Transaksi di-refund | Update status pesanan dan informasikan customer |
Retries & Reliability
Bukasir melakukan percobaan pengiriman webhook hingga 6 kali jika server Anda tidak merespons dengan status 2xx: pengiriman synchronous saat status berubah, lalu retry dengan backoff 1 menit, 5 menit, 15 menit, 1 jam, dan 6 jam. Setelah itu ditandai gagal permanen dan merchant menerima email notifikasi.
- Selalu kirim response 200 secepat mungkin. Proses berat bisa dilakukan secara async.
- Implementasikan idempotency — webhook yang sama mungkin dikirim lebih dari sekali.
- Gunakan database untuk mencatat order_id dan status yang sudah diproses.
Contoh Implementasi Lengkap
<?php
// webhook.php — verifikasi HMAC + rekonsiliasi + idempotency
$secret = getenv('BUKASIR_WEBHOOK_SECRET'); // dari Dashboard > Projects > Edit
$apiKey = getenv('BUKASIR_API_KEY');
$rawBody = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_BUKASIR_SIGNATURE'] ?? '';
$timestamp = $_SERVER['HTTP_X_BUKASIR_TIMESTAMP'] ?? '';
// 1. Verifikasi HMAC + timestamp (WAJIB, jangan cek X-Bukasir-Webhook saja)
if (!ctype_digit($timestamp) || abs(time() - (int) $timestamp) > 300) {
http_response_code(403);
die('Stale timestamp');
}
$expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
if (!hash_equals($expected, strtolower(trim($signature)))) {
http_response_code(403);
error_log("[Bukasir Webhook] Invalid signature from " . $_SERVER['REMOTE_ADDR']);
die('Forbidden');
}
$data = json_decode($rawBody, true);
$orderId = $data['order_id'] ?? '';
$status = $data['transaction_status'] ?? ''; // status Midtrans, bukan status platform
// 2. Idempotency — jangan proses order yang sama dua kali
if (sudahDiproses($orderId, $status)) {
http_response_code(200);
die(json_encode(['success' => true]));
}
// 3. Rekonsiliasi via /api/status — sumber kebenaran sebelum kirim barang
$res = bukasirStatus($apiKey, $orderId);
if (!$res || ($res['status'] ?? '') !== 'completed') {
http_response_code(200); // webhook diterima, pesanan JANGAN diproses
die(json_encode(['success' => true]));
}
// 4. Cocokkan nominal + pastikan order milik Anda, baru proses
// if ((float)$res['amount'] + (float)$res['fee'] !== $orderDbTotal) die('Nominal beda');
switch ($status) {
case 'capture':
// Kartu kredit — cek fraud_status
if (($data['fraud_status'] ?? '') === 'accept') {
updateOrderStatus($orderId, 'paid');
}
break;
case 'settlement':
updateOrderStatus($orderId, 'paid');
sendConfirmationEmail($data);
break;
case 'expire':
updateOrderStatus($orderId, 'expired');
break;
case 'cancel':
case 'deny':
updateOrderStatus($orderId, $status);
break;
case 'refund':
updateOrderStatus($orderId, 'refunded');
break;
}
http_response_code(200);
echo json_encode(['success' => true]);
?>