Webhook trạng thái hóa đơn
Webhook trạng thái hoá đơn của HiTechCloud Pay: nhận thông báo đẩy khi hoá đơn được ký số, cấp mã CQT, bị huỷ hoặc thay thế, thay cho việc hỏi vòng liên tục.
Thay vì gọi polling endpoint theo dõi trạng thái, bạn có thể đăng ký một URL webhook để hệ thống tự động gửi POST mỗi khi trạng thái hóa đơn thay đổi. Mỗi payload được ký HMAC-SHA256 để bạn xác thực nguồn gốc.
Các sự kiện được đẩy
| Sự kiện | Thời điểm kích hoạt |
|---|---|
invoice.approved | Hóa đơn đã được Cơ quan Thuế cấp mã thành công |
invoice.signed | Hóa đơn đã ký số nhưng chưa có mã CQT (hóa đơn không mã) |
invoice.rejected | Cơ quan Thuế từ chối cấp mã (sai dữ liệu) |
invoice.canceled | Hóa đơn bị hủy |
invoice.replaced | Hóa đơn được lập hóa đơn thay thế |
batch.completed | Một lô hóa đơn hàng loạt đã xử lý xong |
Đặc tả Endpoint đăng ký webhook
| Mục | Giá trị |
|---|---|
| Method | POST |
| URL | https://einvoice-api.hitechcloud.vn/v1/webhooks |
| Headers | Authorization: Bearer <TOKEN>, Content-Type: application/json |
Bảng tham số đầu vào
| Tham số | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
url | string | Có | URL HTTPS nhận sự kiện trên hệ thống của bạn |
events | array | Có | Danh sách mã sự kiện muốn nhận (hoặc ["*"] để nhận tất cả) |
secret | string | Không | Chuỗi bí mật dùng ký HMAC-SHA256; nếu bỏ trống hệ thống tự sinh |
curl -X POST "https://einvoice-api.hitechcloud.vn/v1/webhooks" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-system.vn/hooks/einvoice",
"events": ["invoice.approved", "invoice.rejected"],
"secret": "whsec_your_shared_secret"
}'{
"event": "invoice.approved",
"sent_at": "2026-10-31T09:41:03+07:00",
"data": {
"reference_code": "INV-HTC-2026-8899",
"invoice_number": "00005678",
"cqt_code": "M1-26-8899A1",
"status": "approved",
"total_amount": 3960000
}
}Xác thực chữ ký HMAC
Mỗi request webhook mang header X-HTC-Signature chứa HMAC-SHA256 của toàn bộ body ký bằng secret. Tính lại và so sánh để chắc chắn request đến từ HiTechCloud:
<?php
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_HTC_SIGNATURE'] ?? '';
$secret = getenv('HTC_EINV_WEBHOOK_SECRET');
$expected = hash_hmac('sha256', $payload, $secret);
if (!hash_equals($expected, $signature)) {
http_response_code(401);
exit('Invalid signature');
}
$event = json_decode($payload, true);
// Xử lý $event['event'] và $event['data']...
http_response_code(200);200 trong vòng 5 giây. Nếu endpoint của bạn lỗi hoặc timeout, hệ thống thử lại tối đa 5 lần theo cấp số nhân (1 phút, 5 phút, 30 phút, 2 giờ, 6 giờ).Thay vì gọi polling endpoint theo dõi trạng thái, bạn có thể đăng ký một URL webhook để hệ thống tự động gửi POST mỗi khi trạng thái hóa đơn thay đổi. Mỗi payload được ký HMAC-SHA256 để bạn xác thực nguồn gốc.
Các sự kiện được đẩy
| Sự kiện | Thời điểm kích hoạt |
|---|---|
invoice.approved | Hóa đơn đã được Cơ quan Thuế cấp mã thành công |
invoice.signed | Hóa đơn đã ký số nhưng chưa có mã CQT (hóa đơn không mã) |
invoice.rejected | Cơ quan Thuế từ chối cấp mã (sai dữ liệu) |
invoice.canceled | Hóa đơn bị hủy |
invoice.replaced | Hóa đơn được lập hóa đơn thay thế |
batch.completed | Một lô hóa đơn hàng loạt đã xử lý xong |
Đặc tả Endpoint đăng ký webhook
| Mục | Giá trị |
|---|---|
| Method | POST |
| URL | https://einvoice-api.hitechcloud.vn/v1/webhooks |
| Headers | Authorization: Bearer <TOKEN>, Content-Type: application/json |
Bảng tham số đầu vào
| Tham số | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
url | string | Có | URL HTTPS nhận sự kiện trên hệ thống của bạn |
events | array | Có | Danh sách mã sự kiện muốn nhận (hoặc ["*"] để nhận tất cả) |
secret | string | Không | Chuỗi bí mật dùng ký HMAC-SHA256; nếu bỏ trống hệ thống tự sinh |
Xác thực chữ ký HMAC
Mỗi request webhook mang header X-HTC-Signature chứa HMAC-SHA256 của toàn bộ body ký bằng secret. Tính lại và so sánh để chắc chắn request đến từ HiTechCloud:
200 trong vòng 5 giây. Nếu endpoint của bạn lỗi hoặc timeout, hệ thống thử lại tối đa 5 lần theo cấp số nhân (1 phút, 5 phút, 30 phút, 2 giờ, 6 giờ).curl -X POST "https://einvoice-api.hitechcloud.vn/v1/webhooks" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-system.vn/hooks/einvoice",
"events": ["invoice.approved", "invoice.rejected"],
"secret": "whsec_your_shared_secret"
}'{
"event": "invoice.approved",
"sent_at": "2026-10-31T09:41:03+07:00",
"data": {
"reference_code": "INV-HTC-2026-8899",
"invoice_number": "00005678",
"cqt_code": "M1-26-8899A1",
"status": "approved",
"total_amount": 3960000
}
}<?php
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_HTC_SIGNATURE'] ?? '';
$secret = getenv('HTC_EINV_WEBHOOK_SECRET');
$expected = hash_hmac('sha256', $payload, $secret);
if (!hash_equals($expected, $signature)) {
http_response_code(401);
exit('Invalid signature');
}
$event = json_decode($payload, true);
// Xử lý $event['event'] và $event['data']...
http_response_code(200);