DevVN Docs SuperShip

Webhook và đồng bộ trạng thái

Không có webhook thì bạn phải bấm Làm mới trạng thái từng đơn để biết hàng tới đâu. Khai xong, SuperShip chủ động báo về và đơn tự đổi trạng thái — và ở đây bạn tự đăng ký được bằng một nút, không phải nhờ ai.

Vận hành Bước 6 / 7 Cập nhật 06.09.2026

Mã bảo mật và đăng ký webhook

Vào WooCommerce → SuperShip, tab Webhook.

Tab Webhook với khối Mã bảo mật, danh sách webhook đã đăng ký và khối Đăng ký Webhook
Mã bảo mật trong ảnh là giá trị mẫu. Bấm vào ảnh để phóng to.
  1. Webhook — tab thứ tư.
  2. Mã bảo mật — chuỗi bí mật gắn vào URL webhook dưới dạng tham số. Chỉ yêu cầu có mã đúng mới được xử lý, nên người ngoài không giả mạo SuperShip bắn dữ liệu vào website bạn được. Plugin sinh sẵn, bạn không phải nghĩ.
  3. Đăng ký Webhook — bấm là plugin tự gọi API SuperShip và khai URL. Xong thì webhook hiện trong bảng Webhook đã đăng ký ngay trên đó.

Bên cạnh ô mã bảo mật có nút Tạo lại (sinh mã mới) và Lưu mã bảo mật.

Đổi mã bảo mật là phải đăng ký lại webhook

Chính plugin ghi ngay dưới ô: "Sau khi thay đổi mã, bạn phải đăng ký lại webhook với URL mới bên dưới." Mã cũ hết hiệu lực lập tức, SuperShip vẫn gọi vào URL cũ nên không có gì tới nữa. Bấm Tạo lại xong thì bấm luôn Lưu mã bảo mật rồi Đăng ký Webhook.

Webhook báo những gì

SuperShip gửi về hai loại sự kiện:

  • Cập nhật trạng thái đơn hàng — đơn được lấy, đang giao, giao thành công, chuyển hoàn…
  • Cập nhật cân nặng — SuperShip cân lại gói hàng và báo khối lượng thật. Rất đáng theo dõi vì đây là căn cứ tính cước cuối cùng.

Ánh xạ trạng thái

SuperShip có nhiều trạng thái, WooCommerce chỉ có vài cái. Bảng này quyết định mỗi trạng thái SuperShip đẩy đơn của bạn sang trạng thái WooCommerce nào.

Bảng đồng bộ trạng thái với cột Mã, Trạng thái SuperShip và Trạng thái WooCommerce
Bấm vào ảnh để phóng to.
  1. Trạng thái WooCommerce — chọn cho từng mã trạng thái SuperShip. Để Không đồng bộ nghĩa là bỏ qua mốc đó, và đó là mặc định hợp lý cho phần lớn các dòng.

Bảng có nút Đồng bộ trạng thái ở trên để kéo lại danh sách trạng thái mới nhất từ SuperShip. Chỉnh xong bấm Lưu ánh xạ.

Thực tế chỉ nên ánh xạ vài mốc quan trọng:

Mốc SuperShipTrạng thái WooCommerce nên chọn
Đã lấy hàng / đang giaoTrạng thái riêng kiểu Đang giao hàng nếu bạn có, hoặc Đang xử lý.
Giao thành côngHoàn thành.
Huỷ / khách từ chối nhậnĐã huỷ.
Chuyển hoàn về người gửiMột trạng thái riêng để bạn nhận ra hàng đang quay về.
Các mốc trung gian còn lạiKhông đồng bộ — ánh xạ hết chỉ làm đơn nhảy loạn xạ.
Cẩn thận với trạng thái Hoàn thành

Trong WooCommerce, chuyển sang Hoàn thành thường kéo theo email cảm ơn gửi cho khách, cộng điểm thưởng, trừ kho. Chỉ ánh xạ mốc giao thành công vào đó.

Cách kiểm tra đã chạy đúng chưa

  1. Bấm Đăng ký Webhook và xem bảng Webhook đã đăng ký có xuất hiện dòng nào không.
  2. Bấm Đồng bộ trạng thái để kéo danh sách trạng thái, rồi ánh xạ vài mốc chính.
  3. Đăng một đơn thử và chờ SuperShip đổi trạng thái.
  4. Mở đơn trên website — trạng thái phải đổi theo bảng ánh xạ, và mục Đơn hàng ghi chú ghi lại lần cập nhật đó.

Lỗi thường gặp

Hiện tượngCách xử lý
Bấm Đăng ký Webhook báo lỗiAPI Token sai hoặc website không truy cập được từ ngoài. Webhook cần URL công khai — website chạy trên máy nội bộ thì SuperShip không gọi tới được.
Đăng ký xong mà trạng thái vẫn không đổiKiểm bảng ánh xạ: mốc đó có đang để Không đồng bộ không. Cũng bấm Đồng bộ trạng thái để chắc danh sách mã là mới nhất.
Trước có chạy, giờ dừng hẳnBạn vừa bấm Tạo lại mã bảo mật mà chưa đăng ký lại webhook, hoặc website đổi tên miền.
Đơn nhảy trạng thái liên tụcÁnh xạ quá nhiều mốc. Đặt lại phần lớn về Không đồng bộ.
Website chặn webhookTường lửa hoặc plugin bảo mật chặn REST API. Nhờ hosting mở cho đường dẫn /wp-json/ của plugin.

Tiếp theo: dựng trang tra cứu cho khách.

Hỗ trợ Zalo