Đăng ký Endpoint Webhook
Đăng ký endpoint webhook HiTechCloud Pay: yêu cầu kỹ thuật của endpoint hợp lệ, đăng ký qua bảng điều khiển hoặc API, gửi thử và quản lý nhiều endpoint.
Endpoint là URL công khai trên máy chủ của bạn, nơi HiTechCloud Pay gửi HTTP POST mỗi khi có giao dịch khớp cấu hình. Trang này mô tả chi tiết cách khai báo và quản lý endpoint.
Yêu cầu kỹ thuật của endpoint
- HTTPS bắt buộc trên Production: chứng chỉ SSL/TLS hợp lệ, không chấp nhận self-signed.
- Công khai truy cập được: không nằm sau VPN nội bộ hay chặn toàn bộ IP ngoài (xem trang Bảo mật để whitelist đúng dải IP).
- Chỉ nhận HTTP POST với
Content-Type: application/json. - Phản hồi nhanh: trả HTTP
200/201kèm{"success": true}trong vòng tối đa 30 giây (khuyến nghị dưới 2 giây). - Không chuyển hướng (redirect): HiTechCloud Pay không đi theo HTTP 301/302; hãy dùng URL cuối cùng.
Cách 1: Đăng ký qua bảng điều khiển
- Đăng nhập
https://my.hitechcloud.vn→ mục Webhooks → Thêm Webhook. - Tên: đặt tên gợi nhớ (ví dụ: Website Bán Hàng).
- URL Webhook: dán URL endpoint của bạn.
- Loại giao dịch: chọn 'Tiền vào', 'Tiền ra' hoặc 'Tất cả'.
- Tài khoản áp dụng: chọn tất cả hoặc từng tài khoản ngân hàng cụ thể.
- Phương thức xác thực: khuyến nghị HMAC-SHA256, lưu lại SECRET_KEY hệ thống sinh ra.
- Bấm Lưu, sau đó Gửi thử (Test Ping) để kiểm chứng.
Cách 2: Đăng ký qua API
Nếu bạn cần tự động hóa (ví dụ khởi tạo webhook cho từng chi nhánh), hãy dùng API quản lý webhook với khóa API quản trị.
https://my.hitechcloud.vn/api/v1/webhooksKiểm thử tại chỗTrả về đối tượng webhook kèm `id` và `secret` — hãy lưu secret ngay vì nó chỉ hiển thị một lần.
{
"success": true,
"data": {
"id": "wh_7c1a92f0",
"name": "Website Ban Hang",
"url": "https://yourdomain.com/api/hitechcloud-webhook",
"transferType": "in",
"authType": "hmac",
"secret": "whsec_3f9b2c7d8e1a4650b2c9d0e1f2a3b4c5",
"status": "active",
"createdAt": "2026-10-31T10:12:00+07:00"
}
}Gửi thử (Test Ping)
Test Ping gửi một payload rỗng có cờ event: "webhook.ping" tới endpoint để xác nhận URL hoạt động. Endpoint chỉ cần trả {"success": true} với HTTP 200. Ping không tạo giao dịch và không ghi vào lịch sử đối soát.
{
"event": "webhook.ping",
"message": "Ping from HiTechCloud Pay",
"timestamp": 1793000000
}Quản lý nhiều endpoint
Bạn có thể đăng ký nhiều endpoint cùng lúc, mỗi cái cho một mục đích khác nhau. HiTechCloud Pay sẽ bắn song song tới tất cả webhook đang bật mà khớp điều kiện giao dịch.
| Trạng thái | Ý nghĩa |
|---|---|
active | Đang hoạt động, nhận webhook bình thường. |
paused | Tạm dừng, không nhận webhook cho tới khi bật lại. |
failing | Nhiều lần gửi gần đây đều lỗi; hệ thống vẫn retry nhưng cảnh báo bạn kiểm tra. |
disabled | Đã tắt vĩnh viễn hoặc bị vô hiệu do lỗi kéo dài. |
Endpoint là URL công khai trên máy chủ của bạn, nơi HiTechCloud Pay gửi HTTP POST mỗi khi có giao dịch khớp cấu hình. Trang này mô tả chi tiết cách khai báo và quản lý endpoint.
Yêu cầu kỹ thuật của endpoint
- HTTPS bắt buộc trên Production: chứng chỉ SSL/TLS hợp lệ, không chấp nhận self-signed.
- Công khai truy cập được: không nằm sau VPN nội bộ hay chặn toàn bộ IP ngoài (xem trang Bảo mật để whitelist đúng dải IP).
- Chỉ nhận HTTP POST với
Content-Type: application/json. - Phản hồi nhanh: trả HTTP
200/201kèm{"success": true}trong vòng tối đa 30 giây (khuyến nghị dưới 2 giây). - Không chuyển hướng (redirect): HiTechCloud Pay không đi theo HTTP 301/302; hãy dùng URL cuối cùng.
Cách 1: Đăng ký qua bảng điều khiển
- Đăng nhập
https://my.hitechcloud.vn→ mục Webhooks → Thêm Webhook. - Tên: đặt tên gợi nhớ (ví dụ: Website Bán Hàng).
- URL Webhook: dán URL endpoint của bạn.
- Loại giao dịch: chọn 'Tiền vào', 'Tiền ra' hoặc 'Tất cả'.
- Tài khoản áp dụng: chọn tất cả hoặc từng tài khoản ngân hàng cụ thể.
- Phương thức xác thực: khuyến nghị HMAC-SHA256, lưu lại SECRET_KEY hệ thống sinh ra.
- Bấm Lưu, sau đó Gửi thử (Test Ping) để kiểm chứng.
Cách 2: Đăng ký qua API
Nếu bạn cần tự động hóa (ví dụ khởi tạo webhook cho từng chi nhánh), hãy dùng API quản lý webhook với khóa API quản trị.
https://my.hitechcloud.vn/api/v1/webhooksKiểm thử tại chỗTrả về đối tượng webhook kèm `id` và `secret` — hãy lưu secret ngay vì nó chỉ hiển thị một lần.
Gửi thử (Test Ping)
Test Ping gửi một payload rỗng có cờ event: "webhook.ping" tới endpoint để xác nhận URL hoạt động. Endpoint chỉ cần trả {"success": true} với HTTP 200. Ping không tạo giao dịch và không ghi vào lịch sử đối soát.
Quản lý nhiều endpoint
Bạn có thể đăng ký nhiều endpoint cùng lúc, mỗi cái cho một mục đích khác nhau. HiTechCloud Pay sẽ bắn song song tới tất cả webhook đang bật mà khớp điều kiện giao dịch.
| Trạng thái | Ý nghĩa |
|---|---|
active | Đang hoạt động, nhận webhook bình thường. |
paused | Tạm dừng, không nhận webhook cho tới khi bật lại. |
failing | Nhiều lần gửi gần đây đều lỗi; hệ thống vẫn retry nhưng cảnh báo bạn kiểm tra. |
disabled | Đã tắt vĩnh viễn hoặc bị vô hiệu do lỗi kéo dài. |
{
"success": true,
"data": {
"id": "wh_7c1a92f0",
"name": "Website Ban Hang",
"url": "https://yourdomain.com/api/hitechcloud-webhook",
"transferType": "in",
"authType": "hmac",
"secret": "whsec_3f9b2c7d8e1a4650b2c9d0e1f2a3b4c5",
"status": "active",
"createdAt": "2026-10-31T10:12:00+07:00"
}
}{
"event": "webhook.ping",
"message": "Ping from HiTechCloud Pay",
"timestamp": 1793000000
}