Webhook / Callback
BITS Pay mengirim HTTP POST ke callback_url aplikasi kamu setiap status
pembayaran berubah. Tidak perlu polling.
Setup
Isi callback_url saat membuat aplikasi di dashboard. BITS Pay menyimpan
callback_secret per aplikasi untuk menandatangani setiap payload.
callback_secret ditampilkan sekali bersama API key saat
aplikasi dibuat / key di-rotate — simpan keduanya. Hilang? Rotate key dari pengaturan
aplikasi untuk mendapatkan pasangan baru.
callback_allowed di tier features). Tier free
tidak mendapat callback — cek tier kamu di dashboard.
Uji endpoint kamu kapan saja dengan POST /v1/callbacks/test (cukup header API
key, tanpa body). BITS Pay mengirim event callback.test bertanda tangan penuh
ke callback_url aplikasi dan melaporkan status HTTP yang diterima — cocok untuk
memvalidasi verifikasi signature sebelum transaksi pertama. Endpoint ini menolak dengan
400 invalid_status bila callback URL kosong, aplikasi nonaktif, atau tier kamu
tidak mendapat callback.
callback.test hanya berisi { event, test, sent_at } —
tanpa field transaction. Pastikan handler kamu tidak langsung mengakses payload.transaction sebelum
mengecek event.
Request yang dikirim
POST {callback_url}
Content-Type: application/json
X-BITS-Signature: <hmac-sha256-hex>
X-BITS-Timestamp: <unix-seconds>
X-BITS-Event: payment.success
Payload JSON:
{
"event": "payment.success",
"transaction": {
"id": "9b1f2c3e-...",
"order_id": "ORD-001",
"amount": 150000,
"fee": 1000,
"amount_due": 151001,
"status": "success",
"paid_at": "2026-09-02T12:32:00Z"
}
}
Event
| Event | Kapan dikirim |
|---|---|
payment.success |
Pembayaran terkonfirmasi (OCR auto / manual admin) |
payment.failed |
Pembayaran gagal / ditolak |
payment.expired |
Transaksi melewati expired_at tanpa pembayaran |
Verifikasi signature
X-BITS-Signature = HMAC-SHA256 hex dari string
"{X-BITS-Timestamp}.{raw body}", dengan key
callback_secret aplikasi kamu. Wajib verifikasi signature
dan timestamp (toleransi 5 menit) sebelum memproses payload.
// Node.js 18+ / Cloudflare Workers (Web Crypto)
async function verify(rawBody, signature, timestamp, secret) {
if (!signature || !/^[0-9a-f]{64}$/.test(signature)) return false;
// Anti-replay: tolak pesan lebih tua dari 5 menit.
const age = Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp));
if (!Number.isFinite(age) || age > 300) return false;
const enc = new TextEncoder();
const key = await crypto.subtle.importKey(
'raw',
enc.encode(secret),
{ name: 'HMAC', hash: 'SHA-256' },
false,
['verify'],
);
const sigBytes = new Uint8Array(signature.match(/.{2}/g).map((h) => parseInt(h, 16)));
// Signature mencakup timestamp: HMAC(secret, "{timestamp}.{body}").
// crypto.subtle.verify membandingkan MAC secara constant-time — aman dari
// timing attack. Jangan bandingkan hex dengan === (bocor via timing).
return crypto.subtle.verify('HMAC', key, sigBytes, enc.encode(`${timestamp}.${rawBody}`));
}
// Di handler webhook:
const rawBody = await request.text(); // PENTING: raw string, bukan JSON.parse dulu
const signature = request.headers.get('X-BITS-Signature');
const timestamp = request.headers.get('X-BITS-Timestamp');
if (!(await verify(rawBody, signature, timestamp, CALLBACK_SECRET))) {
return new Response('invalid signature', { status: 401 });
}
const payload = JSON.parse(rawBody);
<?php
function verifySignature(string $rawBody, ?string $signature, ?string $timestamp, string $secret): bool
{
if (!$signature || !preg_match('/^[0-9a-f]{64}$/', $signature)) return false;
// Anti-replay: tolak pesan lebih tua dari 5 menit.
if (!is_numeric($timestamp) || abs(time() - (int) $timestamp) > 300) return false;
// Signature mencakup timestamp: HMAC-SHA256(secret, "{timestamp}.{body}").
$expected = hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
// hash_equals membandingkan secara constant-time — aman dari timing attack.
return hash_equals($expected, $signature);
}
// Di handler webhook:
$rawBody = file_get_contents('php://input'); // PENTING: raw string, bukan json_decode dulu
$signature = $_SERVER['HTTP_X_BITS_SIGNATURE'] ?? null;
$timestamp = $_SERVER['HTTP_X_BITS_TIMESTAMP'] ?? null;
if (!verifySignature($rawBody, $signature, $timestamp, CALLBACK_SECRET)) {
http_response_code(401);
exit('invalid signature');
}
$payload = json_decode($rawBody, true);
import hashlib
import hmac
import time
def verify_signature(raw_body: bytes, signature: str, timestamp: str, secret: str) -> bool:
if not signature or len(signature) != 64:
return False
# Anti-replay: tolak pesan lebih tua dari 5 menit.
try:
age = abs(int(time.time()) - int(timestamp))
except (TypeError, ValueError):
return False
if age > 300:
return False
# Signature mencakup timestamp: HMAC-SHA256(secret, "{timestamp}.{body}").
expected = hmac.new(
secret.encode(), f'{timestamp}.'.encode() + raw_body, hashlib.sha256
).hexdigest()
# compare_digest membandingkan secara constant-time — aman dari timing attack.
return hmac.compare_digest(expected, signature)
# Di handler webhook (Flask):
raw_body = request.get_data() # PENTING: raw bytes, bukan request.json dulu
signature = request.headers.get('X-BITS-Signature', '')
timestamp = request.headers.get('X-BITS-Timestamp', '')
if not verify_signature(raw_body, signature, timestamp, CALLBACK_SECRET):
return ('invalid signature', 401)
payload = request.get_json()
Retry
Jika endpoint kamu tidak merespons sukses (HTTP 2xx), callback masuk antrian retry dengan
backoff sampai max_attempts (per tier). Balas cepat dengan 2xx, proses berat
lakukan async. Handler kamu harus idempoten — event yang sama bisa dikirim
ulang.