Chuyển tới nội dung chính

Cấu hình Webhook - Hướng dẫn thiết lập từng bước

Trang này hướng dẫn từng bước thiết lập webhook cho cửa hàng, từ nhập URL nhận đến gửi thử sự kiện và kích hoạt.

Tổng quan​

Việc cấu hình webhook gồm 5 bước chính:

  1. Truy cập tab Webhook trong trang cài đặt API Key
  2. Nhập URL nhận webhook và kiểm tra kết nối
  3. Chọn phương thức xác thực
  4. Chọn các sự kiện muốn đăng ký
  5. Gửi thử từng sự kiện, Kích hoạt và Lưu
Yêu cầu đối với URL nhận webhook
  • URL bắt buộc dùng HTTPS.
  • URL phải là địa chỉ công khai trên Internet — hệ thống từ chối các địa chỉ nội bộ như localhost, IP private (10.x, 192.168.x...), địa chỉ metadata của cloud.
  • Máy chủ nhận cần phản hồi mã 2xx trong vòng 10 giây; phản hồi chậm hơn hoặc mã lỗi sẽ bị tính là gửi thất bại.

Hướng dẫn chi tiết​

Bước 1: Mở tab Webhook

Trên Admin Portal, truy cập Cài đặt → Cài đặt cửa hàng → API Key, sau đó chọn tab Webhook.

Nếu cửa hàng chưa tạo API Key, tab này chỉ hiển thị thông báo yêu cầu tạo API Key ở tab API Key trước. Nếu đã có API Key, form cấu hình webhook sẽ hiển thị ngay (để trống nếu chưa từng lưu webhook).

Trang API Key với 3 tab, đang mở tab Webhook

Bước 2: Nhập URL nhận webhook và kiểm tra kết nối

Nhập địa chỉ máy chủ sẽ nhận dữ liệu sự kiện vào ô URL, ví dụ: https://api.doitac.vn/webhooks/miniai.

Nhấn nút Kiểm tra bên cạnh để hệ thống ping thử tới URL. Kết quả thành công nghĩa là URL có thể truy cập được (kể cả khi máy chủ trả mã 4xx — chỉ cần máy chủ có phản hồi).

Ô nhập URL webhook và nút Kiểm tra kết nối

Bước 3: Chọn phương thức xác thực

Hệ thống hỗ trợ 3 phương thức để máy chủ nhận xác minh rằng webhook thực sự đến từ MiniAI:

  • None — không kèm thông tin xác thực. Chỉ nên dùng khi thử nghiệm.
  • Api Key — tự khai báo các cặp header key–value (ví dụ X-Api-Key: abc123). Hệ thống sẽ gắn các header này vào mọi request webhook. Yêu cầu khai báo ít nhất 1 header.
  • HMAC — hệ thống ký nội dung mỗi request bằng thuật toán HMAC-SHA256 với Secret và gửi chữ ký trong header X-Webhook-Signature. Nếu để trống, Secret sẽ được sinh tự động khi lưu. Đây là phương thức an toàn nhất và được khuyến nghị.
Chọn phương thức xác thực None, Api Key hoặc HMAC

Bước 4: Chọn sự kiện muốn đăng ký

Tại mục Sự kiện, tích chọn các sự kiện muốn nhận thông báo. Các sự kiện được gom theo nhóm (Đơn hàng, Khách hàng, Tồn kho, Sản phẩm...).

Riêng nhóm Đơn hàng và Khách hàng có tùy chọn gộp "Mọi cập nhật đơn hàng" / "Mọi cập nhật khách hàng" — tích một ô này tương đương chọn tất cả các sự kiện cập nhật trong nhóm.

Mỗi dòng sự kiện có nút Test riêng bên phải — dùng để gửi thử payload mẫu của đúng sự kiện đó (xem Bước 5).

Cần chọn ít nhất 1 sự kiện để lưu được cấu hình. Danh sách đầy đủ 24 sự kiện: xem Sự kiện & Payload.

Danh sách chọn sự kiện webhook gom theo nhóm

Bước 5: Gửi thử từng sự kiện, kích hoạt và lưu

  • Bấm nút Test ở dòng sự kiện tại Bước 4 để gửi thử ngay một payload mẫu của đúng sự kiện đó tới URL đã nhập, kèm đúng phương thức xác thực đang cấu hình — không cần lưu form trước, nhưng phải nhập URL hợp lệ (chưa nhập URL sẽ báo "Vui lòng nhập URL webhook trước khi test"). Kết quả hiển thị dạng thông báo nổi góc màn hình: "Đã gửi thử (HTTP ...)" nếu tới được URL, hoặc thông báo lỗi nếu không kết nối được.
  • Bật công tắc Kích hoạt (nằm cạnh tiêu đề "Sự kiện") để webhook bắt đầu hoạt động.
  • Nhấn Lưu ở cuối form để hoàn tất. Lưu lại lần sau sẽ cập nhật cấu hình hiện có, không tạo webhook mới.
Thông báo kết quả sau khi bấm Test cho một sự kiện
Vị trí công tắc Kích hoạt và nút Lưu
Mẹo kiểm thử nhanh

Trong giai đoạn tích hợp, có thể dùng dịch vụ như webhook.site để tạo URL nhận tạm thời và xem trực tiếp payload hệ thống gửi sang, trước khi trỏ về máy chủ thật của bạn.

Tạm dừng webhook

Muốn tạm ngừng nhận thông báo, chỉ cần tắt công tắc Kích hoạt và nhấn Lưu — cấu hình URL, xác thực và sự kiện vẫn được giữ nguyên để bật lại sau.

Sau khi kích hoạt, theo dõi kết quả gửi tại tab Lịch sử gửi webhook.