# Nhận webhook

Webhook gửi dữ liệu tới máy chủ của bạn ngay khi bản ghi thay đổi, thay cho việc gọi Open API liên tục để kiểm tra.

## Cấu hình

Cấu hình trong **Cấu hình › Ứng dụng › Webhook/API**, tab **Webhook URL**, hoặc qua API [Cấu hình webhook](/developers/api/webhook):

| Mục | Ý nghĩa |
|---|---|
| URL nhận webhook | Địa chỉ `https://` công khai của bạn, bắt buộc |
| Email báo lỗi | Nhận email khi gửi webhook thất bại |
| Header | Header gửi kèm mỗi yêu cầu, ví dụ khoá bí mật để máy chủ của bạn xác minh nguồn gửi |
| Loại dữ liệu | Chọn một hoặc nhiều loại bên dưới |

## Loại dữ liệu

| Loại | Gửi khi | Nội dung |
|---|---|---|
| `orders` | Đơn hàng được tạo hoặc cập nhật | [WebhookOrderResponse](/developers/api/schemas#webhookorderresponse) |
| `customers` | Khách hàng được tạo hoặc cập nhật | [WebhookCustomerResponse](/developers/api/schemas#webhookcustomerresponse) |
| `products` | Sản phẩm được tạo hoặc cập nhật | [WebhookProductResponse](/developers/api/schemas#webhookproductresponse) |
| `variations_warehouses` | Tồn kho của mẫu mã thay đổi | [WebhookInventoryResponse](/developers/api/schemas#webhookinventoryresponse) |
| `auto_call` | Cuộc gọi tự động kết thúc | [WebhookAutoCallResponse](/developers/api/schemas#webhookautocallresponse) |

## Nhận webhook

POS gửi `POST` với nội dung JSON và các header đã cấu hình. Máy chủ của bạn cần:

- Trả mã `2xx` trong vòng 30 giây. Mã khác hoặc quá thời gian đều tính là thất bại.
- Xử lý nặng (gọi hệ thống khác, ghi nhiều bảng) ở hàng đợi riêng, trả `2xx` trước.
- Kiểm tra header bí mật đã cấu hình để chỉ nhận yêu cầu từ POS.
- Chấp nhận nhận lại cùng một bản ghi nhiều lần (khi thử lại hoặc khi bản ghi đổi liên tiếp): dùng mã bản ghi và thời gian cập nhật để bỏ qua bản cũ.

## Gửi lại khi thất bại

- Lần gửi đầu thất bại: gửi email báo lỗi (nếu đã cấu hình), gửi lại sau 10 phút, rồi sau 30 phút nữa. Sau đó dừng.
- Máy chủ của bạn lỗi liên tục: POS tạm hoãn gửi để tránh dồn tải, rồi gửi tiếp khi máy chủ trả lời bình thường.
- URL không hợp lệ: POS tự tắt webhook của cửa hàng. Sửa URL rồi bật lại.

Bỏ lỡ dữ liệu trong lúc máy chủ ngừng: đọc lại qua Open API, lọc theo thời gian cập nhật (xem [Phân trang](/developers/api#phan-trang)).