Bảo mật & Chữ ký
Bảo mật Loa thông báo HiTechCloud Pay: bảo vệ Client Secret và access token, xác minh chữ ký webhook, chống phát lặp bằng requestId và whitelist IP cho thiết bị SoundBox.
Loa SoundBox nhận lệnh phát âm thanh qua API xác thực bằng access token và nhận sự kiện qua webhook có chữ ký. Trang này tổng hợp các biện pháp bảo mật khi tích hợp thiết bị.
Bảo vệ khoá & token
- Giữ
client_id/client_secretở phía server; không nhúng vào ứng dụng phía khách. - Lưu access token vào cache theo TTL (6000 giây) và cấp lại khi gặp
TOKEN_EXPIRED, tránh tạo token cho mỗi lần bắn thông báo. - Giữ khoá bí mật trong biến môi trường hoặc kho bí mật, luân chuyển định kỳ.
Chống phát lặp bằng requestId (idempotency)
Mỗi lệnh thông báo nên gắn một requestId duy nhất. Hệ thống bỏ qua lệnh có requestId trùng để loa không đọc lặp một giao dịch. Hãy sinh requestId theo định danh giao dịch của bạn.
Xác thực chữ ký webhook sự kiện loa
Webhook sự kiện loa được ký HMAC-SHA256 trên raw body, chữ ký đặt trong header X-HiTechCloud-Signature. Luôn xác thực bằng so sánh chống timing-attack trước khi xử lý.
Xác thực chữ ký webhook (Node.js)
const crypto = require('crypto');
function verifySpeakerWebhook(rawBody, received, secretKey) {
const expected = crypto.createHmac('sha256', secretKey).update(rawBody).digest('hex');
const a = Buffer.from(expected);
const b = Buffer.from(received || '');
return a.length === b.length && crypto.timingSafeEqual(a, b);
}Xác thực chữ ký webhook (Python)
import hmac, hashlib
def verify_speaker_webhook(raw_body: bytes, received: str, secret_key: str) -> bool:
expected = hmac.new(secret_key.encode(), raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, received or "")Whitelist IP & thực hành an toàn
- Chỉ chấp nhận webhook từ dải IP của HiTechCloud Pay; từ chối phần còn lại.
- Chỉ gọi API phát thông báo từ phía server, không từ thiết bị đầu cuối.
- Ghi log
requestIdvà trạng thái phát để đối soát khi loa không đọc. - Dùng Môi trường thử nghiệm (Sandbox) để kiểm thử luồng trước khi chạy thật.
Không tin dữ liệu webhook khi chưa xác thực chữ ký. Kết hợp
requestId duy nhất với kiểm tra trạng thái phát để tránh phát lặp. Xem thêm Mã lỗi.