Tổng quan Webhook - Nhận thông báo thay đổi dữ liệu theo thời gian thực
Webhook là tính năng cho phép hệ thống của đối tác hoặc bên thứ ba tự động nhận thông báo mỗi khi dữ liệu trên cửa hàng có thay đổi — ví dụ đơn hàng mới được tạo, khách hàng cập nhật số điện thoại, tồn kho biến động, sản phẩm thay đổi giá...
Thay vì phải gọi API liên tục để kiểm tra dữ liệu mới (polling), hệ thống đối tác chỉ cần đăng ký một URL nhận webhook. Khi sự kiện xảy ra, hệ thống sẽ tự động gửi (POST) dữ liệu sự kiện tới URL đó theo thời gian thực.
Tổng quan
Tính năng Webhook nằm trong trang Cài đặt → Cài đặt cửa hàng → API Key, gồm 3 tab:
| Tab | Chức năng |
|---|---|
| API Key | Quản lý API Key của cửa hàng (dùng cho Open API) |
| Webhook | Cấu hình URL nhận webhook, phương thức xác thực và các sự kiện muốn đăng ký |
| Lịch sử gửi webhook | Theo dõi toàn bộ các lần gửi webhook: trạng thái, số lần thử, mã phản hồi HTTP, nội dung payload |
Tính năng Webhook gắn liền với API Key của cửa hàng. Cửa hàng cần được kích hoạt gói dịch vụ có tính năng Tích hợp API Key và đã tạo API Key trước khi cấu hình webhook.
Cách hoạt động
- Cửa hàng cấu hình webhook: nhập URL nhận, chọn phương thức xác thực và các sự kiện muốn nhận, sau đó kích hoạt.
- Khi một sự kiện đã đăng ký xảy ra (ví dụ: đơn hàng mới), hệ thống tạo một bản ghi gửi (delivery) và đưa vào hàng đợi xử lý.
- Hệ thống gửi HTTP POST chứa dữ liệu sự kiện (JSON) tới URL đã đăng ký, kèm header xác thực tương ứng.
- Nếu máy chủ nhận trả về mã 2xx → ghi nhận Đã gửi. Nếu lỗi → hệ thống tự động thử lại theo lịch giãn cách (5 phút → 30 phút → 3 giờ), tối đa 4 lần.
- Toàn bộ quá trình được ghi lại trong tab Lịch sử gửi webhook để tra soát.
Các nhóm sự kiện hỗ tr ợ
Hệ thống hiện hỗ trợ 24 loại sự kiện thuộc 9 nhóm dữ liệu:
- Đơn hàng — tạo mới, đổi trạng thái, thanh toán, hủy
- Khách hàng — tạo mới, đổi số điện thoại, theo dõi OA, cập nhật khác
- Tồn kho — biến động do đơn hàng, chuyển kho, điều chỉnh thủ công, nhập hàng loạt, xóa
- Sản phẩm — tạo mới, cập nhật, xóa
- Tin nhắn ZNS — thay đổi trạng thái gửi
- Chiến dịch ZNS — thay đổi trạng thái chiến dịch
- Yêu cầu tư vấn — tạo mới, thay đổi trạng thái xử lý
- Đánh giá — tạo mới, thay đổi trạng thái duyệt
- Điểm thưởng — tạo mới, thay đổi trạng thái
Chi tiết từng sự kiện và cấu trúc dữ liệu gửi đi: xem Sự kiện & Payload.
Lợi ích
- Nhận dữ liệu thay đổi theo thời gian thực, không cần gọi API kiểm tra liên tục
- Giảm tải cho cả hai hệ thống, tiết kiệm chi phí hạ tầng
- Hỗ trợ 3 phương thức xác thực (không xác thực / API Key header / chữ ký HMAC) phù hợp nhiều mức độ bảo mật
- Cơ chế tự động thử lại khi gửi thất bại, đảm bảo không bỏ sót sự kiện
- Lịch sử gửi đầy đủ giúp tra soát và xử lý sự cố nhanh chóng
Làm theo hướng dẫn từng bước tại Cấu hình Webhook để thiết lập webhook đầu tiên chỉ trong vài phút.
Các trang liên quan
- Cấu hình Webhook — hướng dẫn thiết lập URL, xác thực, chọn sự kiện và gửi thử
- Sự kiện & Payload — danh mục sự kiện, cấu trúc dữ liệu và hướng dẫn xác minh chữ ký cho lập trình viên
- Lịch sử gửi webhook — theo dõi, lọc và tra soát các lần gửi