Tổng quan cơ chế Async Webhook
Đối với các danh sách lớn (hàng trăm đến hàng ngàn tài khoản), thay vì mở kết nối HTTP chờ liên tục, bạn chỉ cần gửi danh sách kèm `webhookUrl`. Hệ thống sẽ phân luồng ngầm an toàn và tự động gửi thông báo POST kèm chữ ký số HMAC-SHA256 về máy chủ của bạn khi hoàn tất.
Thông số Request khởi tạo Batch
| Thuộc tính | Kiểu dữ liệu | Bắt buộc | Mô tả chi tiết |
|---|---|---|---|
| items | array | Bắt buộc | Mảng danh sách tài khoản (tối đa 1.000 tài khoản). Mỗi phần tử gồm bankCode, accountNumber, clientRef (tùy chọn). |
| webhookUrl | string | Tùy chọn | URL HTTPS máy chủ của bạn để nhận kết quả khi job hoàn tất. |
| webhookSecret | string | Tùy chọn | Khóa bí mật tùy chỉnh để ký HMAC-SHA256. Nếu bỏ trống, hệ thống sử dụng khóa mặc định của tài khoản. |
curl -X POST 'https://api.bankgateway.pro/api/v1/lookup/batch' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: YOUR_API_KEY' \
-d '{
"webhookUrl": "https://your-domain.com/api/webhooks/bankgateway",
"webhookSecret": "your_secure_secret_token_123",
"items": [
{ "bankCode": "MB", "accountNumber": "0783825888", "clientRef": "EMP_01" },
{ "bankCode": "VCB", "accountNumber": "1012345678", "clientRef": "EMP_02" }
]
}'202 Accepted · Tiếp nhận xử lý ngầm
{
"success": true,
"message": "Yêu cầu tra cứu hàng loạt đã được tiếp nhận và đưa vào hàng đợi xử lý",
"data": {
"jobId": "BATCH_1793352313937_acd1c46c",
"totalItems": 2,
"status": "PENDING",
"statusUrl": "/api/v1/lookup/batch/BATCH_1793352313937_acd1c46c",
"webhookUrl": "https://your-domain.com/api/webhooks/bankgateway"
}
}Cấu trúc Webhook Payload gửi về máy chủ của bạn
Khi job đạt trạng thái hoàn tất (COMPLETED hoặc FAILED), BankGateway sẽ gửi một yêu cầu HTTP POST tới `webhookUrl` của bạn với các headers bảo mật:
| Header | Mô tả |
|---|---|
| X-BGW-Event | Tên sự kiện: batch.completed, batch.failed hoặc batch.cancelled |
| X-BGW-Job-Id | Mã định danh công việc (Job ID) |
| X-BGW-Timestamp | Thời gian gửi (Unix timestamp tính bằng giây) |
| X-BGW-Signature | Chữ ký số HMAC-SHA256 theo payload thô (Raw Body) |
| X-BGW-Signature-256 | Chuẩn Stripe format: t={timestamp},v1={signature} |
{
"event": "batch.completed",
"timestamp": 1793352320,
"jobId": "BATCH_1793352313937_acd1c46c",
"tenantId": "ten_01jk98m",
"data": {
"jobId": "BATCH_1793352313937_acd1c46c",
"totalItems": 2,
"processedItems": 2,
"successItems": 2,
"failedItems": 0,
"status": "COMPLETED",
"results": [
{
"bankCode": "MB",
"accountNumber": "0783825888",
"clientRef": "EMP_01",
"status": "SUCCESS",
"outcome": "FOUND",
"accountName": "NGUYEN VAN HOANG",
"message": "Tra cứu thành công"
}
]
}
}Xác minh chữ ký Webhook (Code mẫu)
// Node.js Express Webhook Verification
import crypto from "crypto";
app.post("/api/webhooks/bankgateway", (req, res) => {
const signature = req.headers["x-bgw-signature"];
const rawBody = JSON.stringify(req.body);
const secret = "your_secure_secret_token_123";
const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
if (crypto.timingSafeEqual(Buffer.from(signature, "hex"), Buffer.from(expected, "hex"))) {
console.log("Xác minh Webhook thành công! Xử lý job:", req.body.jobId);
return res.status(200).json({ received: true });
} else {
return res.status(401).send("Invalid Webhook Signature");
}
});Bắn lại Webhook thủ công (Manual Redelivery)
Nếu máy chủ của bạn gặp sự cố bảo trì khi Webhook gửi đến, bạn có thể chủ động kích hoạt gửi lại bất kỳ lúc nào:
curl -X POST 'https://api.bankgateway.pro/api/v1/lookup/batch/BATCH_1793352313937_acd1c46c/retry-webhook' \
-H 'X-API-Key: YOUR_API_KEY'