Giới thiệu
- Webhooks giúp bạn đăng kí lắng nghe các sự kiện phát sinh từ hệ thống của Nhanh.vn, VD:
- Khi có đơn hàng mới, khi đơn gửi sang hãng vận chuyển, khi đơn hàng thay đổi trạng thái.
- Khi có sản phẩm mới, khi có cập nhật sản phẩm, khi xóa sản phẩm.
- Khi có hóa đơn bán hàng mới.
- Khi có phiếu bảo hành mới.
- Click sửa ứng dụng, kéo xuống mục webhooks:
- Tích chọn Bật webhooks.
- Điền Webhooks callback URL (bắt buộc chạy https và response http code = 200).
- Điền Webhooks verify token (giá trị này do bạn tự điền, Nhanh API sẽ gửi kèm webhooksVerifyToken khi bắn webhooks để bạn có thể xác minh dữ liệu là từ Nhanh API bắn sang).
- Chọn các sự kiện muốn đăng kí nhận webhooks và nhấn Lưu.
Bật Webhooks
- Nhanh API sẽ gửi request webhooksEnabled tới Webhooks callback URL của bạn để kiểm tra xem URL này có hoạt động hay không.
{
"event":"webhooksEnabled", // Sự kiện khi bật webhooks
"webhooksVerifyToken":"YOUR_WEBHOOKS_VERIFY_TOKEN", // Webhooks verify token điền trong app của bạn
"data": {
"registeredEvents": { // Các events đã đăng kí
"101":"productAdd",
"102":"productUpdate",
"110":"inventoryChange",
"202":"orderUpdate"
}
}
}
- Với mỗi sự kiện Nhanh.vn sẽ gửi sang 1 request có Content type: application/json và request body là json string.
- VD với sự kiện bật webhooks lên, Nhanh Open API sẽ bắn sang link webhooks của bạn 1 request như sau:
Event: Webhooks enabled
curl --location --request POST 'https://webhook.site/a1f7177c-f622-4570-b420-ddf79f3b83e9' \
--header 'Content-Type: application/json' \
--data-raw '{
"event":"webhooksEnabled",
"webhooksVerifyToken":"YOUR_WEBHOOKS_VERIFY_TOKEN",
"data": {
"registeredEvents": {
"101":"productAdd",
"102":"productUpdate",
"110":"inventoryChange",
"202":"orderUpdate"
}
}
}'
Chú ý: Webhooks sẽ chỉ bắn với các dữ liệu mới, các dữ liệu quá khứ (phát sinh trước thời điểm app được cấp quyền hoặc bật webhooks) sẽ không có sự kiện bắn lại.
{
"event": "orderAdd", // Sự kiện khi có đơn hàng mới
"businessId": bigint,
"webhooksVerifyToken": string,
"data": {
// order's information
"customerName": string,
"customerMobile": string,
...
// order product's information
"products": [
]
}
}
- event: (string) Tên sự kiện:
Event | Description |
|---|---|
webhooksEnabled | Sự kiện khi bạn bật webhooks hoặc NhanhAPI kiểm tra webhooks của bạn có còn hoạt động hay không (thường dùng khi tỉ lệ phản hồi response webhooks của bạn có tỉ lệ thành công thấp) |
productAdd | Thêm sản phẩm mới |
productUpdate | Cập nhật sản phẩm |
productDelete | Xóa sản phẩm |
inventoryChange | Thay đổi tồn kho của sản phẩm |
orderAdd | Thêm đơn hàng mới |
orderUpdate | Cập nhật đơn hàng |
orderDelete | Xóa đơn hàng |
- businessId: (bigint) ID doanh nghiệp trên nhanh.vn, dùng khi ứng dụng của bạn tích hợp cho nhiều doanh nghiệp, thì businessId giúp phân biệt dữ liệu của doanh nghiệp nào.
- Riêng sự kiện event = webhooksEnabled sẽ không có businessId.
- webhooksVerifyToken: (string) Key xác minh khi nhận dữ liệu, tương ứng với webhooks verify token trong app của bạn.
- data: (json string) Dữ liệu của sự kiện này.
- Hệ thống của bạn cần response http code 200 để NhanhAPI xác nhận bạn đã xử lý thành công.
- Nếu hệ thống của bạn không phản hồi trong vòng 10 giây, hoặc http code != 200, webhooks sẽ được bắn lại tối đa 3 lần (cách nhau 5, 10, 30 phút).
- Nếu hệ thống của bạn xử lý webhooks với tỉ lệ thành công thấp, tùy mức độ, NhanhAPI sẽ có thể:
- Gọi lại sự kiện webhooksEnabled để kiểm tra link webhooks của bạn có hoạt động hay không.
- Tắt webhooks của app: Bạn cần làm lại các bước bật webhooks như đã mô tả ở trên để mở lại webhooks.
- Khóa app: Bạn cần liên hệ với đội kĩ thuật của Nhanh.vn qua email [email protected] để được mở lại app.
Chú ý: bạn chỉ nên bật webhooks và điền Webhooks callback URL khi bạn đã có link này, không để link liên tục ở tình trạng lỗi (301, 302, 403, 404, 500...) để tránh bị tắt webhooks hoặc khóa app.
- Khi nhận webhooks từ Nhanh.vn bắn sang, bạn có thể gặp phải các tình huống lỗi, xem chi tiết lỗi và cách khắc phục bên dưới:
- Khi bạn bật được webhooks lên và nhận được sự kiện webhooksEnabled, đây chỉ là webhooks test của hệ thống.
- Để nhận được webhooks của doanh nghiệp, thì app của bạn cần được 1 tài khoản thuộc doanh nghiệp đó đăng nhập cấp quyền cho ứng dụng của bạn. Xem lại các bước khởi tạo ứng dụng và đăng nhập cấp quyền tại đây.
- Ở các trang như chi tiết đơn hàng, chi tiết sản phẩm... sẽ có 1 tab API lưu lại tất cả lịch sử nhận API request và gửi webhooks, xin vui lòng kiểm tra kĩ dữ liệu trước khi báo lỗi.
- Lỗi này có thể do nhiều nguyên nhân: Tên miền không hoạt động, server của bạn bị lỗi hoặc phản hồi quá chậm, Firewall của bạn chặn IP của Nhanh.
- Webhooks của Nhanh sẽ được gửi đi từ IP 34.80.32.50 và 34.80.42.152.
- Nếu Firewall của bạn yêu cầu whitelist IP, bạn cần add thêm các IP bên trên.
- Chú ý: các IP này có thể được bổ sung thêm hoặc đổi IP mới, xin vui lòng theo dõi change log để cập nhật thông tin.
Khi bạn test bằng Postman, mặc định Postman sẽ bật "Automatically follow redirects", bạn cần tắt cài đặt này đi, nếu không khi tự test sẽ thấy http code trả về 200 nhưng thực tế đang trả về 301 / 302. Có 2 cách tắt:
- Cách 1: Tắt cho toàn bộ request: Vào menu File > Settings > Tắt: Automatically follow redirects
Postman: Tắt toàn bộ Automatically follow redirects
- Cách 2: Tắt từng tab request: chọn Settings và tắt Automatically follow redirects
Postman: Tắt từng tab Automatically follow redirects
- Nếu bạn dùng Wordpress và có cài plugin Wordfence thì có thể bị lỗi trả về http code 503 và không bật được webhooks lên hoặc nhận webhooks từ Nhanh.vn bắn sang bị chập chờn.
- Cách khắc phục: Gỡ plugin này khỏi Wordpress.
Last modified 2mo ago