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.

Bật webhooks

  • Vào danh sách ứng dụng, click vào tên ứng dụng để vào trang chi tiết.
  • 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).
    • Đ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
1
{
2
"event": "webhooksEnabled", // Sự kiện khi bật webhooks
3
"webhooksVerifyToken": string,
4
"data": {
5
"registeredEvents": { // Các event đã đăng kí
6
101: "productAdd",
7
102: "productUpdate",
8
110: "inventoryChange",
9
202: "orderUpdate"
10
}
11
}
12
}
Copied!

Nhận webhooks

  • 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

Webhooks data

  • event: để phân biệt loại sự kiện là gì.
  • businessId: 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.
  • webhooksVerifyToken: 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: chứa dữ liệu đi kèm với sự kiện này.
1
{
2
"event": "orderAdd", // Sự kiện khi có đơn hàng mới
3
"businessId": int,
4
"webhooksVerifyToken": string,
5
"data": {
6
// order's information
7
"customerName": string,
8
"customerMobile": string,
9
...
10
// order product's information
11
"products": [
12
13
]
14
}
15
}
Copied!

Webhooks response

  • Hệ thống của bạn cần reponse 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 15 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ể:
    • 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.