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.

Xem Markdown

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ệnThời điểm kích hoạt
invoice.approvedHóa đơn đã được Cơ quan Thuế cấp mã thành công
invoice.signedHóa đơn đã ký số nhưng chưa có mã CQT (hóa đơn không mã)
invoice.rejectedCơ quan Thuế từ chối cấp mã (sai dữ liệu)
invoice.canceledHóa đơn bị hủy
invoice.replacedHóa đơn được lập hóa đơn thay thế
batch.completedMột lô hóa đơn hàng loạt đã xử lý xong

Đặc tả Endpoint đăng ký webhook

MụcGiá trị
MethodPOST
URLhttps://einvoice-api.hitechcloud.vn/v1/webhooks
HeadersAuthorization: Bearer <TOKEN>, Content-Type: application/json

Bảng tham số đầu vào

Tham sốKiểuBắt buộcMô tả
urlstringCóURL HTTPS nhận sự kiện trên hệ thống của bạn
eventsarrayCóDanh sách mã sự kiện muốn nhận (hoặc ["*"] để nhận tất cả)
secretstringKhôngChuỗi bí mật dùng ký HMAC-SHA256; nếu bỏ trống hệ thống tự sinh
cURL đăng ký webhook
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"
  }'
Payload webhook mẫu (gửi tới URL của bạn)
{
  "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:

Xác thực chữ ký webhook bằng PHP
<?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);
Hãy trả HTTP 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ờ).