Cấu trúc Webhook Events, JSON Payload & Chữ ký HMAC

Bài viết này cung cấp cấu trúc dữ liệu JSON Payload của các sự kiện Webhook mà TrolyPage gửi tới URL Callback của bạn khi có biến động dữ liệu thời gian thực — kèm cách xác thực chữ ký HMAC để đảm bảo request thực sự đến từ TrolyPage.

Cần dev xác nhận

Cấu trúc JSON payload (3 event dưới) lấy từ dữ liệu thật hiện có và đáng tin. Tuy nhiên header tên chữ ký, giá trị secret, và lịch retry chính xác cần đội dev TrolyPage xác nhận. Các chỗ ghi «cần xác nhận» dùng placeholder an toàn — thay bằng giá trị thật khi có.

1. Đăng ký Webhook URL

Để nhận sự kiện, bạn cần cho TrolyPage biết callback URL của bạn và chọn sự kiện muốn nhận («cần xác nhận UI/endpoint đăng ký»):

1. Tạo endpoint HTTPS công khai trên server của bạn (vd https://api.yourshop.com/trolypage-webhook).
2. Đăng ký URL này + chọn event trong trang cấu hình webhook của TrolyPage (hoặc qua Developer API nếu có endpoint cấu hình).
3. Lấy Webhook Signing Secret (bí mật dùng ký chữ ký — xem mục 5).
4. Server của bạn phải phản hồi HTTP 200 trong 5 giây cho mọi POST từ TrolyPage.

Đăng ký webhook — cần xác nhận

Hiện chưa rõ webhook URL được đăng ký qua UI nào hay qua API endpoint nào. Liên hệ dev để bổ sung hướng dẫn đăng ký chính xác + nơi lấy signing secret.

2. Sự kiện Tin nhắn mới đến (message_received)

Bắn ra khi có tin nhắn mới từ khách hàng gửi tới Facebook Messenger, Zalo OA hoặc Zalo Personal:

{
  "event": "message_received",
  "timestamp": 1774889400,
  "tenant_id": 1042,
  "data": {
    "message_id": "msg_9f8a7b6c5d4e",
    "channel": {
      "type": "facebook_msg",
      "id": "page_123456789"
    },
    "customer": {
      "id": 8520,
      "name": "Nguyễn Văn A",
      "phone": "0912345678",
      "avatar_url": "https://graph.facebook.com/12345/picture"
    },
    "content": {
      "text": "Sản phẩm A giá bao nhiêu tiền shop?",
      "attachments": []
    },
    "ai_handled": true
  }
}

---

3. Sự kiện Đơn hàng cập nhật (order_updated)

Bắn ra khi đơn hàng đổi trạng thái (pending → confirmed → shipping → completed):

{
  "event": "order_updated",
  "timestamp": 1774889450,
  "tenant_id": 1042,
  "data": {
    "order_id": "DH-9821",
    "status": "confirmed",
    "total_amount": 350000,
    "currency": "VND",
    "payment_status": "paid",
    "customer": {
      "id": 8520,
      "name": "Nguyễn Văn A",
      "phone": "0912345678"
    },
    "items": [
      {
        "product_id": 101,
        "product_name": "Áo thun Polo Cotton",
        "quantity": 1,
        "price": 350000
      }
    ]
  }
}

---

4. Sự kiện Thanh toán thành công (payment_completed)

Bắn ra khi hệ thống SePay / VietQR khớp mã đối soát tiền nộp ~0.5s:

{
  "event": "payment_completed",
  "timestamp": 1774889452,
  "tenant_id": 1042,
  "data": {
    "transaction_id": "sp_tx_881923",
    "order_id": "DH-9821",
    "gateway": "sepay_vcb",
    "amount_received": 350000,
    "reference_code": "DH9821",
    "status": "success"
  }
}

Danh sách event đầy đủ

Các event khác (vd message_sent, customer_created, order_created, ticket_*) — liên hệ dev để bổ sung đầy đủ danh sách + payload.

---

5. Xác thực chữ ký Webhook (HMAC) — BẮT BUỘC

Mọi POST từ TrolyPage kèm header chứa chữ ký HMAC-SHA256 của body, ký bằng Webhook Signing Secret của bạn. Bạn phải verify trước khi xử lý để tránh request giả mạo.

Header chữ ký («cần xác nhận tên header + format»):

X-TrolyPage-Signature: sha256=75739d26e89c...   # HMAC-SHA256 của raw body

Verify bằng Node.js:

import crypto from "node:crypto";

function verifyTrolyPageWebhook(rawBody, signatureHeader, signingSecret) {
  const expected = crypto
    .createHmac("sha256", signingSecret)
    .update(rawBody, "utf8")
    .digest("hex");
  const received = signatureHeader.replace(/^sha256=/, "");
  // Dùng timingSafeEqual để chống timing attack
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(received, "hex");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Verify bằng PHP:

function verifyTrolyPageWebhook(string $rawBody, string $signatureHeader, string $signingSecret): bool {
    $expected = hash_hmac('sha256', $rawBody, $signingSecret);
    $received = preg_replace('/^sha256=/', '', $signatureHeader);
    return hash_equals($expected, $received); // hash_equals chống timing attack
}

Nếu KHÔNG verify

Bỏ qua bước verify = endpoint của bạn chấp nhận bất kỳ ai cũng có thể POST payload giả (vd báo “đã thanh toán” giả). Đây là lỗ hổng bảo mật nghiêm trọng. Luôn verify chữ ký + dùng HTTPS.

Tên header + thuật toán — cần xác nhận

Tên header (X-TrolyPage-Signature), format (sha256=... vs hex thuần), và body dùng để ký (raw body vs JSON normalize) cần dev xác nhận. Nếu TrolyPage chưa hỗ trợ chữ ký, yêu cầu dev thêm trước khi dùng webhook cho nghiệp vụ nhạy cảm (payment).

---

6. Yêu cầu phản hồi HTTP 200 & Retry Schedule

• Máy chủ của bạn phải trả HTTP 200 OK trong vòng 5 giây.
• Nếu trả mã lỗi (4xx/5xx) hoặc timeout > 5s → sự kiện vào Retry Queue với Exponential Backoff.

Lịch retry dự kiến («cần xác nhận số chính xác»):

Lần thử	Độ trễ sau lần trước
1 (retry đầu)	~1 phút
2	~5 phút
3	~30 phút
4	~2 giờ
5 (cuối)	~12 giờ

Sau ~24 giờ vẫn fail → sự kiện vào Dead-letter («cần xác nhận có DLQ + cách xem/khôi phục») và TrolyPage báo qua Trung tâm thông báo.

Xử lý idempotent

Vì có retry, endpoint của bạn phải idempotent — xử lý cùng message_id/order_id/transaction_id nhiều lần không sinh tác dụng phụ trùng. Lưu ID đã xử lý (vd Redis/DB) và bỏ qua bản trùng.

---

Bài viết liên quan

• Developer API Reference — REST API (Customers/Orders/Messages).
• Troubleshooting Webhook — Khắc phục lỗi webhook (trễ tin, 401, verify token).
• Tích hợp Zapier & Webhook — Tự động hóa No-code.