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.

Xem Markdown

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

  1. Đăng nhập https://my.hitechcloud.vn và vào mục API Access → Webhook.
  2. Nhập URL điểm nhận (HTTPS) trên server của bạn.
  3. 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

HeaderMô tả
X-HitechcloudPay-SignatureChữ ký HMAC-SHA256 của toàn bộ body, ký bằng Webhook Secret
X-HitechcloudPay-EventTê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ệnMô tả
transaction.createdPhát sinh giao dịch mới (tiền vào hoặc ra)
sub_account.receivedMột tài khoản ảo nhận được tiền