Webhook biến động số dư
Webhook HiTechCloud Pay API: nhận thông báo tức thời khi tài khoản ngân hàng hoặc tài khoản ảo (VA) phát sinh giao dịch tiền vào, tiền ra.
Thay vì liên tục gọi API để dò giao dịch mới, bạn có thể đăng ký một URL webhook để HiTechCloud Pay chủ động gửi dữ liệu giao dịch ngay khi phát sinh biến động số dư.
Cấu hình URL webhook
- Đăng nhập
https://my.hitechcloud.vnvà vào mục API Access → Webhook. - Nhập URL điểm nhận (HTTPS) trên server của bạn.
- Lưu lại Webhook Secret để xác minh chữ ký mỗi lần nhận.
Cấu trúc gói tin gửi đến (Payload)
POST body gửi tới URL của bạn
{
"event": "transaction.created",
"data": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"transaction_date": "2026-10-31 09:15:00",
"account_number": "9988776655",
"va": "VA001",
"transfer_type": "in",
"amount_in": 1500000,
"amount_out": 0,
"transaction_content": "DH100234 chuyen tien mua VPS",
"reference_number": "FT2610310001",
"code": "DH100234",
"bank_brand_name": "Vietcombank"
}
}Header xác minh
| Header | Mô tả |
|---|---|
X-HitechcloudPay-Signature | Chữ ký HMAC-SHA256 của toàn bộ body, ký bằng Webhook Secret |
X-HitechcloudPay-Event | Tên sự kiện, ví dụ transaction.created |
Xác minh chữ ký (PHP)
Kiểm tra chữ ký HMAC-SHA256
<?php
$secret = getenv('HITECHCLOUD_PAY_WEBHOOK_SECRET');
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_HITECHCLOUDPAY_SIGNATURE'] ?? '';
$expected = hash_hmac('sha256', $payload, $secret);
if (!hash_equals($expected, $signature)) {
http_response_code(401);
exit('Chữ ký không hợp lệ');
}
$event = json_decode($payload, true);
// Xử lý giao dịch tại đây...
http_response_code(200);
echo 'OK';Luôn xác minh chữ ký trước khi xử lý và phản hồi mã
200 thật nhanh. Mọi logic nặng nên đưa vào hàng đợi để tránh timeout; hệ thống sẽ thử gửi lại nếu không nhận được 200.| Sự kiện | Mô tả |
|---|---|
transaction.created | Phát sinh giao dịch mới (tiền vào hoặc ra) |
sub_account.received | Một tài khoản ảo nhận được tiền |
Thay vì liên tục gọi API để dò giao dịch mới, bạn có thể đăng ký một URL webhook để HiTechCloud Pay chủ động gửi dữ liệu giao dịch ngay khi phát sinh biến động số dư.
Cấu hình URL webhook
- Đăng nhập
https://my.hitechcloud.vnvà vào mục API Access → Webhook. - Nhập URL điểm nhận (HTTPS) trên server của bạn.
- Lưu lại Webhook Secret để xác minh chữ ký mỗi lần nhận.
Cấu trúc gói tin gửi đến (Payload)
Header xác minh
| Header | Mô tả |
|---|---|
X-HitechcloudPay-Signature | Chữ ký HMAC-SHA256 của toàn bộ body, ký bằng Webhook Secret |
X-HitechcloudPay-Event | Tên sự kiện, ví dụ transaction.created |
Xác minh chữ ký (PHP)
Luôn xác minh chữ ký trước khi xử lý và phản hồi mã
200 thật nhanh. Mọi logic nặng nên đưa vào hàng đợi để tránh timeout; hệ thống sẽ thử gửi lại nếu không nhận được 200.| Sự kiện | Mô tả |
|---|---|
transaction.created | Phát sinh giao dịch mới (tiền vào hoặc ra) |
sub_account.received | Một tài khoản ảo nhận được tiền |
POST body gửi tới URL của bạn
{
"event": "transaction.created",
"data": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"transaction_date": "2026-10-31 09:15:00",
"account_number": "9988776655",
"va": "VA001",
"transfer_type": "in",
"amount_in": 1500000,
"amount_out": 0,
"transaction_content": "DH100234 chuyen tien mua VPS",
"reference_number": "FT2610310001",
"code": "DH100234",
"bank_brand_name": "Vietcombank"
}
}Kiểm tra chữ ký HMAC-SHA256
<?php
$secret = getenv('HITECHCLOUD_PAY_WEBHOOK_SECRET');
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_HITECHCLOUDPAY_SIGNATURE'] ?? '';
$expected = hash_hmac('sha256', $payload, $secret);
if (!hash_equals($expected, $signature)) {
http_response_code(401);
exit('Chữ ký không hợp lệ');
}
$event = json_decode($payload, true);
// Xử lý giao dịch tại đây...
http_response_code(200);
echo 'OK';