Đă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.

Xem Markdown

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/201 kè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

  1. Đăng nhập https://my.hitechcloud.vn → mục Webhooks → Thêm Webhook.
  2. Tên: đặt tên gợi nhớ (ví dụ: Website Bán Hàng).
  3. URL Webhook: dán URL endpoint của bạn.
  4. Loại giao dịch: chọn 'Tiền vào', 'Tiền ra' hoặc 'Tất cả'.
  5. 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ể.
  6. Phương thức xác thực: khuyến nghị HMAC-SHA256, lưu lại SECRET_KEY hệ thống sinh ra.
  7. 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ị.

POSThttps://my.hitechcloud.vn/api/v1/webhooks

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.

Headers
Body
Phản hồi khi tạo webhook thành công
{
  "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.

Payload của Test Ping
{
  "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.
pausedTạm dừng, không nhận webhook cho tới khi bật lại.
failingNhiề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.