Giới thiệu về Webhooks#
Khi ứng dụng của bạn cần thông tin về các sự kiện cụ thể đã xảy ra trong cửa hàng, ứng dụng có thể đăng ký webhook của PosApp như một cơ chế để nhận dữ liệu gần như thời gian thực về các sự kiện này.PosApp webhooks hữu ích để giữ cho ứng dụng của bạn đồng bộ với dữ liệu PosApp hoặc như một trình kích hoạt để thực hiện hành động bổ sung sau khi sự kiện đó xảy ra. Chúng cũng là một giải pháp thay thế hiệu quả cho việc liên tục thăm dò các thay đổi đối với dữ liệu của cửa hàng.Hướng dẫn này cung cấp thông tin cơ bản về thời điểm sử dụng API so với webhooks, cũng như thuật ngữ và h ành vi chính dành riêng cho webhooks của PosApp.Ví dụ về thời điểm ứng dụng của bạn có thể sử dụng webhooks (use case)#
Tích hợp dữ liệu nhập, xuất kho với hệ thống riêng của đối tác.
Xóa dữ liệu khách hàng khỏi cơ sở dữ liệu của đối tác.
Tích hợp dữ liệu về đơn hàng với phần mềm kế toán.
Cập nhật giá bảo hành của sản phẩm dựa trên những thay đổi về giá của sản phẩm.
Sự kiện webhook#
Webhooks được xử lý theo sự kiện. Ứng dụng của bạn đăng ký một hoặc nhiều sự kiện để nhận webhooks. Sau khi cài đặt sự kiện cho cửa hàng, ứng dụng của bạn sẽ nhận được webhooks mỗi khi loại sự kiện đó được kích hoạt cho cửa hàng đó.Sự kiện webhook xác định loại tin nhắn sự kiện mà ứng dụng của bạn nhận được. Ví dụ: ứng dụng của bạn có thể đăng ký sự kiện products.create để được thông báo về các sản phẩm mới được tạo từ PosApp. Tên sự kiện xác định bản chất của sự kiện đã xảy ra.Những sự kiện được PosApp hỗ trợ#
| Tên sự kiện | Mô tả | Trạng thái | Data Schema |
|---|
warehouse.import.create | Tạo phiếu nhập kho | Sẵn sàng | Click to view |
warehouse.export.create | Tạo phiếu xuất kho | Coming soon | |
orders.create | Có đơn hàng mới | Sẵn sàng | Click to view |
orders.update | Đơn hàng có cập nhật mới | Sẵn sàng | Click to view |
products.create | Sản phẩm mới được tạo | Coming soon | |
products.update | Sản phẩm có cập nhật mới | Coming soon | |
Một số lưu ý khi xử lý sự kiện của PosApp#
PosApp không xử lý cùng sự kiện trên nhiều webhook#
PosApp hỗ trợ tạo nhiều webhook để xử lý sự kiện, nhưng nếu bạn đăng ký cùng 1 sự kiện trên nhiều webhook PosApp sẽ chỉ xử lý trên webhook có sự kiện được tạo cũ nhất.Làm việc với các phiên bản#
Tham số api_version trong payload của request sẽ chỉ định phiên bản nào của Admin API được sử dụng để trả về cấu trúc dữ liệu tương ứng.Xử lý trùng lặp webhooks#
Trong một số trường hợp hiếm hoi, ứng dụng của bạn có thể nhận được cùng một sự kiện webhook nhiều lần. PosApp khuyên bạn nên phát hiện các sự kiện webhook trùng lặp bằng cách so sánh tham số event_id với event_id của các sự kiện trước đó.Sử dụng Webhook#
Hướng dẫn cấu hình webhook#
Để thiết lập webhook mới, Vào "Thiết lập" chọn "Webhook" bấm thêm mới webhook và thêm đầy đủ URL cho webhook của bạn (ví dụ: https://www.example.com/posapp-webhook) vào phần "Webhook URL". Lưu ý rằng URL cần phải là URL có thể truy cập công khai qua internet. Ví dụ: 127.0.0.1 và localhost URL sẽ không hoạt động vì máy chủ của PosApp sẽ không thể liên lạc với máy tính local của bạn (bạn có thể tham khảo sử dụng ngrok để test môi trường local và https).Webhook URL yêu cầu phải có SSL (https)
Xử lý yêu cầu xác minh#
Sau khi bạn nhập URL webhook, "yêu cầu xác minh" ban đầu sẽ được thực hiện với URL. Xác minh này là một HTTP GET có tham số challenge, là một chuỗi ngẫu nhiên (ví dụ https://www.example.com/posapp-webhook?challenge=abc123). Ứng dụng của bạn cần phản hồi bằng cách phản hồi lại tham số challenge đó, và có tối đa 3 giây để phản hồi yêu cầu xác minh. PosApp sẽ không thực hiện thử lại tự động cho các yêu cầu xác minh.Để tránh đưa vào lỗ hổng XSS được phản ánh, hãy thêm các headers sau trong phản hồi của bạn cho yêu cầu xác minh:'Content-Type: text/plain'
'X-Content-Type-Options: nosniff'
challenge, PosApp sẽ bắt đầu gửi thông báo đến URL webhook mỗi khi c ó sự kiện bạn đã đăng ký. Nếu ứng dụng của bạn không phản hồi đúng, bạn sẽ thấy thông báo lỗi cho bạn biết về sự cố.Nhận thông báo#
Sau khi URL webhook của bạn được thêm vào, ứng dụng của bạn sẽ bắt đầu nhận được thông báo mỗi khi có sự kiện mới. Yêu cầu được gửi với phương thức HTTP POST có payload là JSON:{
"event_id": "008cabdd-a458-4493-92b9-9d90b89f5329",
"event_type": "order.create",
"api_version": "v1",
"data": "<Data schema theo từng sự kiện>"
}
headers sau:X-PosApp-Signature là chữ ký HMAC-SHA256 của payload, sử dụng Secret Key của webhook đã đăng ký làm khóa ký (tham khảo Digital Signature). Điều này cho phép ứng dụng của bạn xác minh rằng thông báo thực sự đến từ PosApp. Bạn nên kiểm tra tính hợp lệ của chữ ký trước khi xử lý (nhưng không bắt buộc).X-PosApp-Triggered-At là thời gian PosApp kích hoạt webhook của sự kiện này.
X-PosApp-Signature: "0348c9446bcedc83e1eaaba8090eb520e011c9aa7706b938943a99261054a2d4",
X-PosApp-Triggered-At: "2023-03-29T18:00:27.877041743Z"
| Header | Mô tả |
|---|
| X-PosApp-Signature | Xác minh dữ liệu. Sử dụng Digital Signature |
| X-PosApp-Triggered-At | Xác định ngày và giờ PosApp kích hoạt webhook. |
| X-PosApp-Retry-Count | Số lần cố gắng gửi lại sự kiện (chỉ có khi được retry ) |
Yêu cầu hiệu suất cho webhook#
Nhanh chóng phản hồi tất cả sự kiện webhook với HTTP status code = 200 OK. Bất kỳ phản hồi nào nằm ngoài phạm vi 200, bao gồm mã chuyển hướng HTTP 3XX, cho biết bạn không nhận được webhook. PosApp sẽ coi những mã này là phản hồi lỗi.Phản hồi tất cả sự kiện webhook tối đa 3 giây.Nếu webhook của bạn không đáp ứng được bất kỳ yêu cầu nào ở trên thì sẽ nhận được thông báo webhook không hoạt động gửi đến email của cửa hàng.Thử lại sự kiện webhook#
PosApp sẽ cố gắng thử lại sự kiện của bạn ngay cả khi chúng bị lỗi (nếu bạn bật tính năng này trong cài đặt của webhook).PosApp sẽ liên tục gửi lại các sự kiện tương tự sau các mốc thời gian như bên dưới (có thể chênh lệch vài giây). Các sự kiện đó với payload hoàn toàn tương tự, nhưng sẽ có truyền thêm ở header của request trường X-PosApp-Retry-Count - chính là số lần gửi lại sự kiện đó.| Lần thứ | Thời gian thử lại |
|---|
| 1 | 30 giây |
| 2 | 1 phút |
| 3 | 1 phút 30 giây |
| 4 | 2 phút |
| 5 | 2 phút 30 giây |
