Webhook Nhanh.vn
Webhook là cách Nhanh.vn tự báo về website mỗi khi tồn kho, sản phẩm hay đơn hàng thay đổi. Không có webhook thì tồn kho trên website chỉ đổi khi bạn bấm đồng bộ tay — dễ bán quá số hàng đang có.
Khai webhook trong app Nhanh.vn
Webhook được khai ngay trong app bạn tạo ở bước 2 bài Kết nối API Nhanh.vn. Kiểm tra lại bốn chỗ:
- Bật webhooks đang bật, Webhooks version là version 3.0.
- Webhooks callback URL đúng bằng dòng 5 ở tab Nhanh.vn của plugin, chạy https.
- Webhooks verify token đúng bằng mã trong ô ở dòng 6.
- Đã tích đủ sự kiện ở bảng dưới.
Nhanh.vn chỉ gửi những thay đổi phát sinh sau khi bạn đã cấp quyền và bật webhook, không gửi lại dữ liệu cũ. Vì vậy vẫn phải đồng bộ sản phẩm một lần đầu.
Sự kiện nào làm gì
| Sự kiện trên Nhanh.vn | Plugin làm gì trên website |
|---|---|
| Cập nhật tồn kho | Cập nhật số tồn của sản phẩm, biến thể đã có ID Nhanh, theo ô Tồn kho ở cài đặt đồng bộ sản phẩm. Chỉ ghi khi số tồn thật sự đổi. |
| Sửa sản phẩm | Cập nhật giá, tồn kho, ảnh, mô tả, cân nặng, kích thước theo các ô đang bật ở cài đặt đồng bộ sản phẩm. Tên và SKU trên website giữ nguyên. |
| Xóa sản phẩm | Chỉ gỡ ID Nhanh khỏi sản phẩm. Sản phẩm trên website không bị xoá hay ẩn — tự ẩn nếu cần. |
| Xóa đơn hàng | Đơn WooCommerce tương ứng chuyển Đã huỷ, và được phép đăng lại lên Nhanh.vn. |
| Sửa đơn hàng | API v2: đổi trạng thái đơn WooCommerce theo bảng ở mục cuối bài. API v3: plugin 1.6.4 nhận nhưng không đổi trạng thái đơn WooCommerce. |
| Thêm sản phẩm, Thêm đơn hàng, Trả hàng 1 phần | Plugin không xử lý — không cần tích. Sản phẩm mới tạo trên Nhanh.vn thì đưa về website ở bước 2 của đồng bộ sản phẩm (Load từ API Nhanh.vn rồi Tạo mới). |
Website kiểm tra webhook thế nào
- Với API v3, Nhanh.vn gửi verify token kèm mỗi lượt. Plugin so với mã đã lưu và so Business ID với ô ở tab Nhanh.vn. Không khớp thì bỏ qua lượt đó.
- Chưa lưu verify token hoặc Business ID thì website từ chối mọi lượt với lỗi
401 Webhook not configured. - Đổi verify token ở plugin thì phải dán mã mới sang app ngay, nếu không mọi lượt sau đó bị bỏ qua.
Mở tab Webhook
- Webhook — tab thứ năm.
- Chạy nền (Background Queue) — mặc định bật. Webhook đến thì plugin lưu vào hàng đợi, trả lời Nhanh.vn ngay, rồi mới xử lý trong nền (bằng Action Scheduler của WooCommerce, không có thì bằng WP-Cron).
Nhanh.vn chờ website trả lời thành công thật nhanh; chậm hay lỗi thì gửi lại tối đa 3 lần, và nếu tỉ lệ thành công thấp kéo dài, Nhanh.vn có thể tắt webhook của app. Tắt chạy nền thì website phải xử lý xong mới trả lời — dễ quá giờ khi Nhanh.vn gửi dồn nhiều lượt cùng lúc.
Tab Webhook Queue
Khi bật chạy nền, thanh tab có thêm Webhook Queue — nơi xem từng lượt webhook đã nhận.
- Webhook Queue — tab ngay sau tab Webhook.
- Ô đếm theo trạng thái — Tất cả, Chờ xử lý, Đang xử lý, Hoàn thành, Đã gộp, Thất bại. Bấm vào một ô để lọc bảng. Ô bên dưới tìm theo ID sản phẩm, ID đơn hay bất kỳ chữ nào trong dữ liệu.
- Retry tất cả failed — xếp lại mọi lượt thất bại vào hàng chờ. Từng dòng thất bại cũng có nút Retry riêng.
- Data — xem nguyên dữ liệu Nhanh.vn gửi về cho lượt đó. Nút Xoá bỏ một dòng; Xoá log đã xử lý dọn các dòng đã xong.
Cách hàng đợi chạy:
- Mỗi lượt xử lý tối đa 20 giây hoặc 25 mục, chạy từng mục một nên không bị xử lý trùng.
- Mục lỗi được thử lại tối đa 3 lần rồi chuyển Thất bại. Mục kẹt ở "Đang xử lý" quá 5 phút thì tự quay về hàng chờ.
- Đã gộp — một sản phẩm có nhiều lượt tồn kho, sửa sản phẩm đang chờ thì lượt cũ được gộp vào lượt mới nhất, đỡ việc mà kết quả vẫn đúng.
- Lịch sử: dòng đã xong hoặc đã gộp giữ khoảng 1 giờ, dòng lỗi giữ 7 ngày, sau đó tự dọn.
Bảng trạng thái đơn hàng (chỉ API v2)
- Trạng thái Woocommerce — chọn trạng thái đơn trên website ứng với từng trạng thái Nhanh.vn, hoặc "Không đồng bộ trạng thái". Mặc định: Thành công → Đã hoàn thành; Thất bại, Hãng vận chuyển hủy đơn, Đang chuyển hoàn, Đã chuyển hoàn → Thất bại; Khách hủy, Hệ thống hủy → Đã hủy.
Bảng chỉ dùng khi website kết nối bằng API v2. Với API v3, trạng thái đơn trên Nhanh.vn không tự đổi trạng thái đơn WooCommerce — bạn cập nhật trạng thái đơn trên website như bình thường. Riêng đơn bị xoá trên Nhanh.vn thì vẫn chuyển Đã huỷ như bảng sự kiện ở trên.
Dữ liệu Nhanh.vn gửi về, xác thực token, cách phản hồi và code PHP mẫu có ở bài webhook Nhanh.vn.
Kiểm tra webhook đã chạy
- Trên Nhanh.vn, đổi tồn kho của một sản phẩm đã có ID Nhanh (nhập hay xuất thử một chiếc).
- Mở tab Webhook Queue: có dòng
inventoryChangemới, vài giây sau thành Hoàn thành. - Mở sản phẩm đó trên website: tồn kho đã đổi.
Plugin có chế độ ghi log chi tiết (filter nhanhvn_debug), nhưng file log nằm trong thư mục plugin, ai biết đường dẫn cũng mở được, và có chứa token cùng thông tin khách. Chỉ bật trong lúc dò lỗi, tắt ngay khi xong và xoá file log. Đừng gửi nguyên file log cho ai — xem bài hook.
Lỗi thường gặp
| Hiện tượng | Nguyên nhân và cách xử lý |
|---|---|
| Đổi tồn trên Nhanh.vn mà Webhook Queue không có dòng nào | Webhook chưa tới được website: callback URL sai hoặc không phải https, chưa bật webhook trong app, chưa tích sự kiện, tường lửa hoặc Cloudflare chặn yêu cầu POST tới /wp-json/, hoặc license đang không hợp lệ (website trả 404). |
| Có dòng nhưng tồn trên website không đổi | Sản phẩm chưa có ID Nhanh, ô Tồn kho ở cài đặt đồng bộ đang tắt, hoặc kho chứa hàng chưa được kéo về ở tab Kho hàng. |
| Dòng đứng mãi ở "Chờ xử lý" | Tác vụ nền không chạy: kiểm tra WooCommerce → Trạng thái → Tác vụ đã lên lịch, và hosting có tắt WP-Cron mà không cài cron thật không. |
Nhiều dòng "Thất bại" với ERR_429 | Nhanh.vn đang giới hạn số lần gọi. Chờ vài phút rồi bấm Retry tất cả failed. |
| Đổi trạng thái đơn trên Nhanh.vn, đơn trên website không đổi | Với API v3 đây là cách plugin 1.6.4 hoạt động (xem khung cảnh báo ở trên). Với API v2: kiểm tra bảng trạng thái và sự kiện Sửa đơn hàng trong app. |
| Nhanh.vn tắt webhook của app | Website trả lỗi hoặc trả lời chậm quá lâu. Bật lại chạy nền, sửa nguyên nhân, rồi bật webhook lại trong app. |
Tiếp theo: đồng bộ khách hàng, hoặc bỏ qua sang vận chuyển & phí ship.