Webhook
Webhook để KiotViet tự báo cho website mỗi khi tồn kho, giá hay sản phẩm thay đổi. Plugin không có lịch đồng bộ định kỳ, nên thiếu webhook thì web chỉ đổi khi bạn tự bấm.
Webhook chạy thế nào
Bán một món tại quầy, KiotViet gọi sang một địa chỉ trên website (Link Webhook) kèm thông tin thay đổi. Plugin ghi lượt gọi vào hàng đợi rồi trả lời ngay, phần cập nhật sản phẩm chạy sau trong nền bằng Action Scheduler, bộ chạy việc nền đi kèm WooCommerce và chạy theo WP-Cron.
Thường thay đổi về web sau vài giây tới khoảng một phút. Website vắng khách, hoặc tắt WP-Cron mà chưa cài cron thật trên máy chủ, thì lâu hơn. Plugin không hẹn một mốc thời gian cố định.
Theo tài liệu Public API của KiotViet, website phải trả lời trong 5 giây; quá 5 giây tính là thất bại, còn trả về mã lỗi 400, 401, 403, 404, 405 thì KiotViet ngưng gửi tới địa chỉ đó.
Mở tab Webhook
- Mở tab Webhook, nơi khai báo và theo dõi webhook.
Mã bí mật và Link Webhook
- Ô Mã bí mật Webhook chứa chuỗi 12 ký tự plugin tự sinh lúc cài. Không có lý do thì không cần đổi.
- Nút Tạo mã mới sinh mã khác. Chỉ dùng khi nghi mã cũ đã lộ.
Dòng Link Webhook có dạng https://ten-mien-cua-ban/wp-json/kiotviet-sync/v1/webhook-mã-bí-mật. Bạn không phải chép link này đi đâu, plugin tự dùng khi đăng ký với KiotViet.
Plugin không kiểm chữ ký của KiotViet, chỉ dựa vào mã nằm trong link. Ai có link là gửi được dữ liệu giả vào website: đổi tên, đổi giá, xoá sản phẩm. Che link khi chụp màn hình nhờ hỗ trợ. Nghi lộ thì bấm Tạo mã mới rồi đăng ký lại webhook như hướng dẫn bên dưới.
Đổi mã hoặc đổi tên miền thì link đổi theo, các webhook cũ vẫn trỏ về link cũ. Bấm Xóa từng dòng trong bảng sự kiện, rồi bấm Đăng ký tất cả webhook. Nút đăng ký tất cả bỏ qua sự kiện đã có dòng, nên phải xoá dòng cũ trước.
Cùng khối còn ô Tự động tạo sản phẩm mới, mặc định tắt. Tắt thì webhook chỉ cập nhật sản phẩm đã có trên web, hàng hoá mới tạo trên KiotViet bị bỏ qua; bạn tạo nó ở tab Đồng bộ sản phẩm. Bật thì hàng hoá mới tự thành sản phẩm trên web.
Đăng ký các sự kiện
- Bấm Đăng ký tất cả webhook một lần, plugin đăng ký hết các sự kiện chưa có. Mỗi dòng còn có nút Đăng ký hoặc Xóa riêng.
Bảng Danh sách các sự kiện Webhook có 11 sự kiện, cột Trạng thái phải là Active. Plugin làm gì với từng sự kiện:
| Sự kiện | Plugin làm gì |
|---|---|
product.update | Cập nhật sản phẩm theo các ô ở tab Đồng bộ sản phẩm. Sản phẩm được đưa về Đã xuất bản và hiện trong cửa hàng. |
product.delete | Xoá vĩnh viễn sản phẩm hoặc biến thể trên web, không vào thùng rác. |
stock.update | Cập nhật tồn kho theo chi nhánh đã chọn, có trừ hàng tạm giữ và số lẻ nếu bạn bật. |
pricebook.update, pricebook.delete, pricebookdetail.update, pricebookdetail.delete | Cập nhật giá khi bảng giá thay đổi đúng là bảng đang dùng cho Giá thường hoặc Giá khuyến mãi. Bảng giá đang làm Giá thường bị xoá thì giá quay về giá niêm yết. |
customer.update, customer.delete | Chỉ xử lý khi chế độ ở tab Đồng bộ khách hàng là KiotViet -> WooCommerce hoặc Cả hai chiều. |
order.update | Đổi trạng thái đơn trên web, chỉ khi bạn bật đồng bộ trạng thái ở tab Đồng bộ đơn hàng. |
invoice.update | Chỉ ghi log, không đổi gì trên web. |
Plugin không nhận webhook danh mục; nhóm hàng mới phải làm lại ở tab Ánh xạ danh mục. Sản phẩm đang bật Không đồng bộ từ KiotViet thì mọi webhook sản phẩm, tồn kho, giá, xoá đều bỏ qua nó.
Sự kiện product.delete xoá vĩnh viễn, không khôi phục được từ thùng rác. Không muốn web xoá theo KiotViet thì bấm Xóa ở dòng product.delete trong bảng (tự đăng ký lại chỉ bật lại webhook bị KiotViet tắt, không tạo lại dòng bạn đã xoá), hoặc bật Không đồng bộ từ KiotViet cho từng sản phẩm cần giữ.
Tự động đăng ký lại khi bị vô hiệu hoá
KiotViet tự tắt webhook khi website trả mã lỗi 4xx hoặc trả lời chậm quá 5 giây, ví dụ lúc hosting quá tải hay đang bảo trì. Ô Tự động đăng ký lại khi bị vô hiệu hóa (mặc định bật) cho plugin kiểm định kỳ và đăng ký lại các webhook của chính website này đang bị tắt.
- Ô Chu kỳ kiểm tra chọn 15 phút, 30 phút, 1 giờ (mặc định), 6 giờ, 12 giờ hoặc 24 giờ.
- Mỗi sự kiện được đăng ký lại tối đa 3 lần trong 24 giờ. Quá mức đó plugin dừng, gửi email cho quản trị viên và hiện thông báo trong trang quản trị.
- Nút Kiểm tra ngay chạy một lượt kiểm ngay khi bấm; nút Xóa bộ đếm & cảnh báo xoá số lần đã thử sau khi bạn sửa xong nguyên nhân.
Webhook bật lại chỉ nhận các thay đổi từ lúc đó trở đi. Thay đổi trong lúc webhook tắt phải đối soát tay theo mục kế tiếp.
Website lỡ webhook thì đối soát thế nào
Website sập, bảo trì, chuyển hosting, hoặc webhook bị KiotViet tắt một thời gian: các thay đổi trong lúc đó không tự về sau. Khi website chạy lại:
- Mở tab Bắt đầu, bấm Kiểm tra lại, xem bước Đăng ký Webhook. Ở tab Webhook, cột Trạng thái các dòng phải là Active; chưa đúng thì bấm Kiểm tra ngay hoặc đăng ký lại.
- Sang tab Đồng bộ sản phẩm, bấm Tải từ API KiotViet để bảng tạm có số mới.
- Bấm Đồng bộ tồn kho, chọn Tất cả sản phẩm.
- Giá hay thông tin sản phẩm cũng đổi trong thời gian đó thì lọc Liên kết WooCommerce là "Đã liên kết (cập nhật)" rồi bấm Đồng bộ tất cả theo filter, hoặc chọn hết rồi đồng bộ trong nền.
Nút Đồng bộ tồn kho đọc số trong bảng tạm, không gọi KiotViet. Bỏ qua bước 2 thì web nhận lại đúng số cũ.
Cơ chế xử lý hàng đợi
KiotViet có thể bắn về hàng trăm thay đổi cùng lúc, ví dụ khi bạn nhập một lô hàng lớn. Hàng đợi nhận hết rồi xử lý dần theo lô. Cùng một sản phẩm, chi nhánh, bảng giá, khách hay đơn bị gửi nhiều lần thì plugin chỉ giữ lần gửi sau cùng.
| Ô | Mặc định, nên đặt thế nào |
|---|---|
| Cơ chế xử lý | Mới (Queue + Dedup) - Khuyến nghị. Chỉ chuyển sang Cũ (Action Scheduler trực tiếp) khi được hỗ trợ yêu cầu. |
| Batch size | 10. Hosting yếu thì giảm xuống 5. |
| Delay giữa các batch (giây) | 1. Máy chủ hay quá tải thì tăng lên. |
| Số lần retry tối đa | 3. Dòng xử lý báo lỗi được thử lại tối đa chừng ấy lần rồi chuyển Thất bại. |
| Tự động dọn rác hàng ngày | Bật. Không bật thì bảng hàng đợi phình to theo thời gian. |
| Giữ lại dữ liệu trong (ngày) | 1 tháng. Dòng cũ hơn bị xoá khi dọn rác. |
| Xóa các status | Hoàn tất và Đã bỏ qua. Dòng Chờ xử lý, Đang xử lý không bao giờ bị xoá tự động. |
Sửa xong bấm Lưu cấu hình queue. Khối Thống kê bên dưới đếm số dòng Chờ xử lý, Đang xử lý, Hoàn tất, Đã bỏ qua, Thất bại và tự làm mới mỗi 10 giây. Các nút Chạy ngay, Xóa Done + Skipped, Xóa Failed, Xóa tất cả dùng để dọn tay; dòng Thất bại đưa về hàng chờ bằng hành động Requeue (đưa về pending). Số Chờ xử lý cứ tăng mà không giảm thường do WP-Cron không chạy; số Thất bại tăng dần là lúc cần bật Ghi log và xem nhật ký.
Tồn kho từ webhook được tính thế nào
Bạn chọn đúng một chi nhánh ở tab Cài đặt API thì plugin lấy luôn số tồn trong webhook. Để trống (mặc định) hoặc chọn nhiều chi nhánh thì mỗi lượt tồn kho đổi, plugin gọi thêm API để lấy đủ tồn từng chi nhánh của sản phẩm đó rồi cộng lại. KiotViet giới hạn các lệnh đọc dữ liệu ở 5.000 lần mỗi giờ, nên cửa hàng đổi tồn hàng nghìn mã một lúc có thể chạm giới hạn này.
Bật ô Xóa cache ở tab Cài đặt API thì sau mỗi lượt cập nhật, plugin xoá bộ nhớ đệm trang của đúng sản phẩm đó để khách thấy số mới.
Kiểm tra webhook có thật sự chạy không
- Mở KiotViet, đổi tồn kho một sản phẩm đã liên kết.
- Đợi 1 tới 2 phút.
- Mở sản phẩm đó trên website xem tồn kho đã đổi chưa.
Chưa đổi thì kiểm theo thứ tự: cột Trạng thái các sự kiện còn Active không; khối Thống kê có dòng mới không và đang kẹt ở Chờ xử lý hay Thất bại; phần Kiểm tra môi trường ở tab Bắt đầu có báo HTTPS, đường dẫn tĩnh hay WP-Cron không. Cần xem chi tiết thì bật Ghi log ở tab Cài đặt API rồi mở WooCommerce → Trạng thái → Nhật ký, nguồn kiotviet-webhook-log.
Còn vướng thì xem Giải đáp thắc mắc. Lập trình viên cần tuỳ biến thì xem Hook cho lập trình viên.