Chuyển đến nội dung chính
Hà Nội DC
Cloud247
10/11/2026 Cập nhật 15/11/2026 6 phút đọc

Kiến trúc Web App thương mại tích hợp Webhook thanh toán, Queue Worker & Cloud247 OpenAPI v1

Mô hình chuẩn khi xây dựng cổng thương mại dịch vụ số: tách luồng HTTP nhận Webhook với Queue Worker bất đồng bộ, xác thực chữ ký HMAC-SHA256 và tự động khởi tạo hạ tầng qua Cloud247 OpenAPI v1.

Trọng tâm: HMAC-SHA256 whsec_* + Queue Worker + Idempotency-Key + POST /v1/orders
Kiến trúc Web App thương mại tách tầng Queue Worker, xác thực chữ ký HMAC-SHA256 Webhook và gọi Cloud247 OpenAPI v1

1. Vì sao phải tách tầng nhận Webhook với Queue Worker xử lý đơn hàng?

Trong các cổng bán dịch vụ số (Cloud VPS, Proxy, phần mềm bản quyền), sai lầm kiến trúc thường gặp là đặt toàn bộ logic cộng số dư ví, gọi API cấp phát tài nguyên và gửi email thông báo ngay bên trong hàm xử lý HTTP của Webhook thanh toán.

Khi cổng thanh toán hoặc hệ thống hạ tầng bắn đồng thời nhiều sự kiện, tiến trình đồng bộ kéo dài quá thời gian chờ sẽ khiến phía gửi đánh dấu thất bại và tự động gửi lặp lại sự kiện. Thiết kế chuẩn là điểm cuối Webhook chỉ kiểm tra chữ ký bảo mật, ghi nhận mã sự kiện duy nhất vào cơ sở dữ liệu, đẩy tác vụ vào hàng đợi (Redis/BullMQ hoặc bảng jobs) và phản hồi HTTP 200 ngay trong vài chục mili-giây.

Màn hình đối soát Webhook thanh toán VietQR tức thì và tự động bàn giao đơn hàng qua REST API v1 trên hạ tầng Cloud247

2. Xác thực chữ ký HMAC-SHA256 chống giả mạo sự kiện Webhook

Mọi yêu cầu gửi tới đường dẫn nhận Webhook đều phải được đối chiếu chữ ký số HMAC-SHA256 tính trên chuỗi nội dung gốc (raw body) kết hợp mốc thời gian để ngăn chặn tấn công phát lại (replay attack):

Xác thực chữ ký HMAC-SHA256 an toàn thời gian (Node.js Backend)
javascript
import crypto from 'node:crypto';

export function verifyCloud247Webhook(rawBody, timestampHeader, signatureHeader, webhookSecret) {
  const nowSec = Math.floor(Date.now() / 1000);
  const ts = Number(timestampHeader);
  if (!Number.isFinite(ts) || Math.abs(nowSec - ts) > 300) {
    return false; // Từ chối gói tin lệch quá 5 phút
  }

  const signedPayload = `${ts}.${rawBody}`;
  const expectedHex = crypto
    .createHmac('sha256', webhookSecret) // khóa whsec_* lưu trong biến môi trường Server
    .update(signedPayload, 'utf8')
    .digest('hex');

  const a = Buffer.from(expectedHex, 'hex');
  const b = Buffer.from(String(signatureHeader || '').replace(/^sha256=/, ''), 'hex');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

3. Chống tạo đơn trùng bằng Idempotency-Key và đối soát với OpenAPI v1

Ở tầng Queue Worker, khi thực thi lệnh đặt mua tài nguyên tự động lên https://api.cloud247.vn/v1, hãy gắn mã đơn nội bộ cố định làm Idempotency-Key để ngay cả khi Worker khởi động lại giữa chừng cũng không bao giờ trừ ví hai lần:

  • Bước báo giá tự động: Worker gọi POST /v1/order-quotes kèm header bắt buộc X-Currency: VND để kiểm tra đơn giá hiện hành và nhận mã khóa giá Quote-Fingerprint.
  • Bước khởi tạo nguyên tử: Gọi POST /v1/orders truyền kèm X-Currency: VND, Idempotency-Key (ví dụ ord-inv-20261114-0089) và Quote-Fingerprint vừa nhận.
  • Bước đối soát định kỳ: Sử dụng khóa phân quyền services:read gọi GET /v1/services để đồng bộ trạng thái thực tế của máy ảo hoặc cổng Proxy về bảng quản trị khách hàng khi mạng chập chờn.

Bài viết kỹ thuật liên quan

Tiếp tục tham khảo các hướng dẫn vận hành cùng chủ đề trên hệ thống Cloud247:

Tất cả 37 bài viết