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

Webhook là đường dây để GHTK tự báo về website mỗi khi vận đơn thay đổi. Có nó thì đơn giao xong tự chuyển sang Đã hoàn thành, khách từ chối nhận thì tự chuyển Đã huỷ, bạn không phải ngồi bấm kiểm tra từng đơn.

Có bắt buộc không

Không bắt buộc, nhưng thiếu nó thì mọi trạng thái đều phải cập nhật tay bằng nút Check đơn hàng trong từng đơn. Shop vài đơn một ngày thì làm tay cũng được; từ vài chục đơn trở lên thì webhook tiết kiệm cho bạn hàng giờ mỗi tuần.

Đăng ký webhook GHTK: đơn WooCommerce tự cập nhật trạng thái — Video 2 phút: vì sao cần webhook, lấy Webhook Link, cấu hình webhook trên trang khách hàng GHTK, chọn trạng thái đồng bộ và kiểm gì khi đơn không tự cập nhật.

Lấy đường dẫn webhook

Vào WooCommerce → Cài đặt GHTK → tab Cài đặt GHTK, kéo xuống khối nền hồng.

Khối Webhook nền hồng với đường dẫn webhook được đánh số 1 và nút Đổi Webhook Key đánh số 2 — Khối Webhook. Mã trong ảnh là mã mẫu. Bấm vào ảnh để phóng to.

Chép nguyên dòng Webhook Link, kể cả phần hash= ở cuối. Đây là đường dẫn để GHTK gửi tin về.
Nút Đổi Webhook Key sinh mã mới. Chỉ dùng khi bạn lỡ để lộ đường dẫn cũ; đổi xong bấm Lưu thay đổi rồi sửa lại URL đích trên GHTK theo đường dẫn mới, không thì trạng thái ngừng cập nhật.

Bấm Lưu thay đổi trước khi chép đường dẫn

Lần đầu vào khối này, mã hiển thị mới chỉ là mã tạm chưa lưu vào cơ sở dữ liệu. Dán vào GHTK trước khi lưu là dán nhầm mã. Bấm Lưu thay đổi ở cuối trang, tải lại trang, rồi mới chép.

Đăng ký webhook trên trang khách hàng GHTK

GHTK cho shop tự cấu hình webhook, không còn phải gửi thư nhờ GHTK đăng ký như trước.

Trang Thông tin tài khoản trên GHTK, mục Cấu hình API ở cột trái đánh số 1 và nút Cấu hình webhook đánh số 2 — Trang khách hàng GHTK, tháng 10/2026. Tên shop, token là dữ liệu mẫu.

Đăng nhập trang khách hàng GHTK, bấm tên shop ở góc trên bên trái, chọn Thông tin tài khoản, rồi chọn Cấu hình API ở cột bên trái.
Ở khối Webhook, bấm Cấu hình webhook. GHTK có thể hỏi mật khẩu tài khoản để xác thực: nhập mật khẩu rồi bấm Xác thực.

Hộp Cấu hình Webhook trên GHTK: Trạng thái Hoạt động số 1, Data format Json số 2, URL đích số 3, nút Lưu thông tin số 4 — Hộp Cấu hình Webhook. Đường dẫn trong ô URL đích là đường dẫn mẫu.

Ở Trạng thái chọn Hoạt động.
Ở Data format chọn Json.
Dán nguyên Webhook Link vừa chép trong plugin vào ô URL đích, kể cả phần hash=. Ô Headers để trống, plugin không cần.
Bấm Lưu thông tin.

Khối Webhook trên GHTK sau khi lưu: dòng URL đích, Data format Json, Trạng thái Đang hoạt động đánh số 1 — Lưu xong, khối Webhook hiện dòng URL đích. Muốn đổi đường dẫn thì bấm Sửa.

Cột Trạng thái phải là Đang hoạt động. Sau đó đăng thử một đơn và theo dõi xem trạng thái có tự đổi không.

Các trường GHTK gửi về và danh sách kiểm khi đơn không tự cập nhật có ở bài webhook GHTK.

Ánh xạ trạng thái GHTK sang WooCommerce

GHTK có hơn hai mươi trạng thái, WooCommerce chỉ có vài trạng thái. Bảng này quyết định trạng thái nào bên GHTK thì đơn trên website chuyển sang trạng thái gì.

Bảng ánh xạ trạng thái GHTK sang trạng thái WooCommerce, cột trái là trạng thái GHTK cột phải là ô chọn trạng thái Woo — Bảng ánh xạ trạng thái. Ảnh chỉ hiện phần đầu, bảng thật dài hơn.

Cột Trạng thái GHTK ghi kèm mã số trong ngoặc, là mã GHTK dùng khi gửi tin về. Bạn không sửa được cột này.
Với dòng (-1) Hủy đơn hàng → Đã hủy, GHTK huỷ vận đơn thì đơn trên website cũng chuyển thành đã huỷ.
Dòng cần giữ đúng trước tiên là (5) Đã giao hàng → Đã hoàn thành. Nhờ nó mà giao hàng xong đơn tự đóng, doanh thu tự vào báo cáo.

Chọn Không đồng bộ trạng thái ở dòng nào thì trạng thái đó GHTK báo về nhưng đơn trên website giữ nguyên. Cấu hình mặc định đã hợp lý với đa số shop:

Trạng thái GHTK	Trạng thái WooCommerce
(5) Đã giao hàng, (6) Đã đối soát, (45) Shipper báo đã giao	Đã hoàn thành
(-1) Huỷ đơn, (11) Đã đối soát công nợ trả hàng, (20) Đang trả hàng, (21) Đã trả hàng	Đã huỷ
(13) Đơn hàng bồi hoàn	Thất bại
Các trạng thái đang giao, đang lấy, delay…	Không đồng bộ, đơn giữ nguyên trạng thái hiện tại

Muốn phân biệt đơn đang giao

Tạo một trạng thái đơn hàng riêng, ví dụ Đang giao, bằng plugin quản lý trạng thái WooCommerce; sau đó gán nó cho dòng (4) Đã điều phối giao hàng/Đang giao hàng. Nhân viên nhìn danh sách đơn là biết ngay đơn nào đang trên đường.

Kiểm tra webhook đã chạy

Đăng một đơn lên GHTK.
Chờ GHTK cập nhật trạng thái (thường sau khi shipper nhận đơn).
Mở đơn ra xem hộp Đăng đơn GHTK: dòng Cập nhật lúc phải đổi mà bạn không bấm Check đơn hàng lần nào. Đó là dấu hiệu webhook đang chạy.
Khách mở đơn ở mục Tài khoản → Đơn hàng sẽ thấy bảng Trạng thái đơn hàng, mỗi lần webhook về thêm một dòng. Khi trạng thái đơn trên website đổi theo bảng ánh xạ, WooCommerce tự ghi một dòng vào ghi chú đơn.

Lỗi thường gặp

Tình huống	Nguyên nhân và cách xử lý
Đã lưu cấu hình webhook mà trạng thái vẫn không tự đổi	Mở lại Cấu hình API trên GHTK: webhook phải ở trạng thái Đang hoạt động và URL đích phải đúng nguyên Webhook Link hiện tại trong plugin, kể cả phần `hash=`.
Website chạy trên máy nội bộ hoặc tên miền thử	GHTK phải gọi vào được website từ Internet. Máy local hay tên miền chưa trỏ ra ngoài thì webhook không bao giờ tới.
Website có tường lửa hoặc Cloudflare chặn	Yêu cầu của GHTK bị chặn trước khi tới WordPress. Cho phép đường dẫn `admin-ajax.php` đi qua, hoặc thêm dải IP của GHTK vào danh sách trắng.
Trạng thái đổi lung tung, đơn đang giao bỗng hoàn thành	Xem lại bảng ánh xạ, có thể ai đó đã gán nhầm một trạng thái trung gian sang Đã hoàn thành.
Vừa bấm Đổi Webhook Key xong thì ngừng cập nhật	Đúng như vậy, mã cũ không còn hiệu lực. Bấm Lưu thay đổi, rồi trên GHTK bấm Sửa ở khối Webhook và dán đường dẫn mới vào URL đích.

Tiếp theo: In hoá đơn và email báo mã vận đơn.