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:

  1. Midtrans mengirim POST notification ke Bukasir (/api/webhook)
  2. Bukasir memverifikasi signature Midtrans (SHA512)
  3. Bukasir mencocokkan gross_amount dengan amount + fee di database — tidak cocok = ditolak
  4. Sebelum completed, Bukasir mengonfirmasi ulang via Midtrans Status API (wajib di mode live)
  5. Bukasir memperbarui status transaksi di database (mapping status Midtrans ke status platform)
  6. Bukasir me-relay notifikasi ke webhook_url merchant Anda, ditandatangani HMAC-SHA256 per project
  7. Field signature_key dihapus dari payload, order_id dikembalikan ke order_id merchant Anda, selain itu dikirim apa adanya
Catatan Payload yang Anda terima adalah notifikasi asli dari Midtrans, bukan format khusus Bukasir. Field-field yang ada mengikuti format standar Midtrans (kecuali signature_key yang dihapus).

Setup Webhook

  1. Login ke dashboard Bukasir
  2. Buka Pengaturan > Profil
  3. Isi field Webhook URL (contoh: https://yourdomain.com/webhook)
  4. Klik Simpan
Peringatan Webhook URL harus menggunakan HTTPS. HTTP tidak didukung demi keamanan.

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 });
});
Tips Keamanan Untuk keamanan tambahan, Anda juga bisa memverifikasi bahwa request berasal dari IP Bukasir atau memeriksa payload secara logis (misalnya order_id yang valid di database Anda).

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)
Catatan Payload dapat mengandung field tambahan lain dari Midtrans tergantung metode pembayaran. Field di atas adalah yang paling umum.

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.

Best Practice
  • 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]);
?>