Trong trang này

Webhooks · Tổng quan & Cấu hình

Webhook là cách QHTech chủ động gửi dữ liệu giao dịch về máy chủ của bạn ngay khi phát sinh biến động số dư — thay vì bạn phải liên tục gọi API để hỏi. Đây là cách tích hợp được khuyến nghị cho các luồng cần xác nhận thanh toán tức thời (cổng thanh toán, nạp tiền tự động, xác nhận đơn hàng…).

#Luồng hoạt động

Khách chuyển khoản
        │
        ▼
Ngân hàng ghi nhận  ──►  QHTech ghi nhận giao dịch
                                │
                                ▼
                 QHTech POST payload JSON  ──►  URL webhook của bạn
                                │
                                ▼
                 Máy chủ bạn trả HTTP 200  ──►  QHTech đánh dấu thành công

Khách hàng chuyển khoản vào tài khoản ngân hàng bạn đã kết nối với QHTech.
QHTech ghi nhận giao dịch (tiền vào hoặc tiền ra).
QHTech gửi một request POST kèm dữ liệu giao dịch (JSON) tới URL bạn đã cấu hình.
Máy chủ của bạn xử lý và trả về HTTP 2xx để báo đã nhận thành công. Nếu không, QHTech sẽ thử lại (xem Phản hồi, Retry & Logs).

#Sự kiện kích hoạt

Mỗi webhook được gắn một sự kiện quy định chiều tiền nào sẽ kích hoạt nó:

Sự kiện	Kích hoạt khi	Ý nghĩa
`in`	Giao dịch tiền vào (credit)	Nhận tiền — dùng để xác nhận thanh toán
`out`	Giao dịch tiền ra (debit)	Chi tiền
`all`	Mọi giao dịch (cả vào lẫn ra)	Nhận tất cả

Đa số tích hợp thanh toán chỉ cần sự kiện in (tiền vào).

#Cấu hình webhook

Vào dashboard QHTech, mở menu Webhooks rồi bấm Thêm webhook mới. Các trường cấu hình:

Trường	Bắt buộc	Mô tả
Tên (`name`)		Nhãn gợi nhớ cho webhook.
URL (`url`)		Địa chỉ endpoint của bạn mà QHTech sẽ `POST` tới. Nên dùng HTTPS.
Token (`token`)		Chuỗi bí mật dùng để bạn xác thực request đến từ QHTech. Bấm nút tạo để sinh chuỗi ngẫu nhiên 50 ký tự.
Sự kiện (`event`)		`in` / `out` / `all` (mặc định `in`).
Tài khoản ngân hàng (`bank_account_id`)		Tài khoản nguồn phát sinh giao dịch sẽ kích hoạt webhook này.
Lọc tài khoản ảo (`virtual_accounts`)	—	Danh sách số tài khoản ảo (VA). Nếu đặt, webhook chỉ kích hoạt khi giao dịch thuộc các VA này.
Bỏ qua nếu không có mã (`skip_if_no_code`)	—	Nếu bật, webhook bỏ qua giao dịch mà QHTech không trích được mã thanh toán từ nội dung chuyển khoản.
Trạng thái (`status`)	—	Bật/tắt. Chỉ webhook đang bật mới được gửi.

#Lưu ý khi thiết lập

URL cần phản hồi nhanh và trả về mã 2xx. Xử lý nghiệp vụ nặng nên đưa vào hàng đợi (queue) để trả về sớm.
Token là bí mật — không để lộ. Bạn sẽ dùng nó để kiểm tra tính xác thực của mỗi request (xem Payload & Xác thực).
Có thể tạo nhiều webhook cho nhiều tài khoản / nhiều hệ thống khác nhau.

Tiếp theo: xem chi tiết cấu trúc payload và cách xác thực request.