Tổng quan

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).

CAUTION

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'

Mục đích của yêu cầu xác minh này là để chứng minh rằng ứng dụng của bạn thực sự muốn nhận thông báo tại URL đó. Nếu bạn vô tình nhập sai URL (hoặc nếu ai đó cố ý nhập máy chủ của bạn làm webhook của họ), ứng dụng của bạn sẽ không phản hồi đúng yêu cầu thách thức và PosApp sẽ không gửi bất kỳ thông báo nào đến URL đó.

Nếu ứng dụng của bạn phản hồi đúng yêu cầu 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

event_id

string

required

ID sự kiện

event_type

string

required

Loại sự kiện

api_version

string

required

Phiên bản api (mặc định v1)

data

required

Có thể là object hoặc array tùy loại sự kiện

Any of

Warehouse import Schema

Order Create Schema

Dữ liệu này chứa trong trường data của payload

string

required

ID phiếu nhập kho

shop_id

integer

required

ID cửa hàng

shop_name

string

required

Tên cửa hàng

facility_id

integer

required

ID kho

facility_name

string

required

Tên kho

transaction_with_id

integer

required

ID nhà cung cấp

transaction_with_name

string

required

Tên nhà cung cấp

code

string

required

Mã phiếu

created_at

string

required

Ngày tạo phiếu. Định dạng Iso

total

number

required

Tổng tiền hàng nhập kho

paid_total

number | null

optional

Tổng tiền đã thanh toán

note

string | null

optional

Ghi chú

status

integer

required

Trạng thái phiếu

discount_price

number | null

optional

Tiền giảm giá

discount_percent

number | null

optional

% giảm giá

surcharge_price

number | null

optional

Tiền phụ thu

surcharge_percent

number | null

optional

% phụ thu

tax_price

number | null

optional

Tiền thuế

tax_percent

number | null

optional

% thuế

shipping

number

required

Phí vận chuyển

items

array [object {16}]

required

Danh sách các sản phẩm nhập trong phiếu

Ví dụ:

{
  "event_id": "008cabdd-a458-4493-92b9-9d90b89f5329",
  "event_type": "order.create",
  "api_version": "v1",
  "data": "<Data schema theo từng sự kiện>"
}

Mỗi request sẽ bao gồm các 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.

Ví dụ:

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 đó.

Test

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

Release

Bạn cần xử lý để webhook hoạt động lại trong khoảng thời gian sự kiện được gửi lại. Nếu webhook của bạn tiếp tục không đáp ứng được yêu cầu trong khoảng thời gian đó, bạn sẽ nhận được thông báo webhook đã bị vô hiệu hóa. Sau khi khắc phục sự cố với webhook xong bạn cần bật lại webhook trong phần thiết lập webhook.

Giới thiệu về Webhooks#

Ví dụ về thời điểm ứng dụng của bạn có thể sử dụng webhooks (use case)#

Sự kiện webhook#

Những sự kiện được PosApp hỗ trợ#

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#

Làm việc với các phiên bản#

Xử lý trùng lặp webhooks#

Sử dụng Webhook#

Hướng dẫn cấu hình webhook#

Xử lý yêu cầu xác minh#

Nhận thông báo#

Yêu cầu hiệu suất cho webhook#

Thử lại sự kiện webhook#

Giới thiệu về Webhooks

Ví dụ về thời điểm ứng dụng của bạn có thể sử dụng webhooks (use case)

Sự kiện webhook

Những sự kiện được PosApp hỗ trợ

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

Làm việc với các phiên bản

Xử lý trùng lặp webhooks

Sử dụng Webhook

Hướng dẫn cấu hình webhook

Xử lý yêu cầu xác minh

Nhận thông báo

Yêu cầu hiệu suất cho webhook

Thử lại sự kiện webhook