Webhook — Tổng quan & đăng ký
Webhook HiTechPos: đăng ký URL để nhận đẩy sự kiện đơn hàng, tồn kho và sản phẩm theo thời gian thực thay cho việc hỏi vòng liên tục.
Thay vì liên tục gọi API để dò thay đổi, bạn đăng ký một URL webhook để HiTechPos gửi sự kiện ngay khi phát sinh. Mọi webhook được phát từ miền https://pos.hitechcloud.vn/webhook.
Cấu hình webhook
- Đăng nhập
https://pos.hitechcloud.vnvà vào API & Tích hợp → Webhook. - Nhập URL điểm nhận (HTTPS) trên server của bạn và chọn các loại sự kiện cần nhận.
- Lưu lại Webhook Secret để xác minh chữ ký mỗi lần nhận.
Cấu trúc gói tin gửi đến (Payload)
POST body gửi tới URL của bạn
{
"event": "order.created",
"shop_id": "shop_0a1b2c3d",
"sent_at": "2026-10-31 10:12:01",
"data": {
"id": "order_900123",
"code": "DH900123",
"status": "confirmed",
"total": 558000,
"warehouse_id": "wh_main"
}
}Header xác minh
| Header | Mô tả |
|---|---|
X-HitechPos-Signature | Chữ ký HMAC-SHA256 của toàn bộ body, ký bằng Webhook Secret |
X-HitechPos-Event | Tên sự kiện, ví dụ order.created |
X-HitechPos-Delivery | ID lần gửi, dùng để chống xử lý trùng (idempotency) |
Xác minh chữ ký (PHP)
Kiểm tra chữ ký HMAC-SHA256
<?php
$secret = getenv('HITECHPOS_WEBHOOK_SECRET');
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_HITECHPOS_SIGNATURE'] ?? '';
$expected = hash_hmac('sha256', $payload, $secret);
if (!hash_equals($expected, $signature)) {
http_response_code(401);
exit('Chu ky khong hop le');
}
$event = json_decode($payload, true);
// Xu ly su kien tai day...
http_response_code(200);
echo 'OK';Luôn xác minh chữ ký trước khi xử lý và phản hồi
200 trong vòng 30 giây. Mọi xử lý nặng nên đưa vào hàng đợi; HiTechPos sẽ thử gửi lại nếu không nhận được 2xx.Thay vì liên tục gọi API để dò thay đổi, bạn đăng ký một URL webhook để HiTechPos gửi sự kiện ngay khi phát sinh. Mọi webhook được phát từ miền https://pos.hitechcloud.vn/webhook.
Cấu hình webhook
- Đăng nhập
https://pos.hitechcloud.vnvà vào API & Tích hợp → Webhook. - Nhập URL điểm nhận (HTTPS) trên server của bạn và chọn các loại sự kiện cần nhận.
- Lưu lại Webhook Secret để xác minh chữ ký mỗi lần nhận.
Cấu trúc gói tin gửi đến (Payload)
Header xác minh
| Header | Mô tả |
|---|---|
X-HitechPos-Signature | Chữ ký HMAC-SHA256 của toàn bộ body, ký bằng Webhook Secret |
X-HitechPos-Event | Tên sự kiện, ví dụ order.created |
X-HitechPos-Delivery | ID lần gửi, dùng để chống xử lý trùng (idempotency) |
Xác minh chữ ký (PHP)
Luôn xác minh chữ ký trước khi xử lý và phản hồi
200 trong vòng 30 giây. Mọi xử lý nặng nên đưa vào hàng đợi; HiTechPos sẽ thử gửi lại nếu không nhận được 2xx.POST body gửi tới URL của bạn
{
"event": "order.created",
"shop_id": "shop_0a1b2c3d",
"sent_at": "2026-10-31 10:12:01",
"data": {
"id": "order_900123",
"code": "DH900123",
"status": "confirmed",
"total": 558000,
"warehouse_id": "wh_main"
}
}Kiểm tra chữ ký HMAC-SHA256
<?php
$secret = getenv('HITECHPOS_WEBHOOK_SECRET');
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_HITECHPOS_SIGNATURE'] ?? '';
$expected = hash_hmac('sha256', $payload, $secret);
if (!hash_equals($expected, $signature)) {
http_response_code(401);
exit('Chu ky khong hop le');
}
$event = json_decode($payload, true);
// Xu ly su kien tai day...
http_response_code(200);
echo 'OK';