Chữ ký & bảo mật
Mỗi yêu cầu webhook được ký HMAC-SHA256 bằng secret của endpoint. Hãy xác minh chữ ký và thời điểm gửi trước khi tin vào nội dung.
LRS gửi POST JSON tới URL của bạn. Bất kỳ ai cũng có thể gọi URL đó, vì vậy chỉ xử lý sự kiện khi chữ ký hợp lệ.
Header
| Header | Giá trị |
|---|---|
| X-LRS-Delivery-ID | Mã lần gửi, giữ nguyên qua các lần thử lại — dùng để bỏ sự kiện trùng. |
| X-LRS-Timestamp | Thời điểm gửi, tính bằng giây Unix. |
| X-LRS-Signature | sha256= cộng chữ ký HMAC-SHA256 ở dạng hex. |
| Content-Type | application/json |
| User-Agent | LRS-Webhook/1 |
Thân yêu cầu
{
"id": "whd_7b1e0c93a4d2f8e65c1a0b9d3e7f2a48",
"event": "order.paid",
"data": { "order_id": "ord_5e1c90a7", "amount": 1990000, "currency": "VND" }
}Cách tính chữ ký
Chữ ký là HMAC-SHA256, khoá là secret của webhook, thông điệp là timestamp, một ký tự xuống dòng, rồi nguyên văn thân yêu cầu:
signature = "sha256=" + hex( HMAC_SHA256( secret, timestamp + "\n" + raw_body ) )Dùng thân yêu cầu thô (chưa parse JSON). Parse rồi serialize lại sẽ làm sai chữ ký.
Ví dụ xác minh (Node.js)
import crypto from "node:crypto";
import express from "express";
const app = express();
const SECRET = process.env.LRS_WEBHOOK_SECRET;
app.post("/lrs/webhook", express.raw({ type: "application/json" }), (req, res) => {
const timestamp = req.get("X-LRS-Timestamp") ?? "";
const signature = req.get("X-LRS-Signature") ?? "";
const expected =
"sha256=" +
crypto
.createHmac("sha256", SECRET)
.update(timestamp + "\n")
.update(req.body)
.digest("hex");
const valid =
signature.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) < 300;
if (!valid || !fresh) return res.sendStatus(401);
const { id, event, data } = JSON.parse(req.body.toString("utf8"));
// Bỏ qua nếu đã xử lý "id" này: LRS có thể gửi lại cùng một sự kiện.
res.sendStatus(204);
});Khuyến nghị bảo mật
- So sánh chữ ký bằng hàm so sánh thời gian hằng (
timingSafeEqual), không dùng===. - Từ chối yêu cầu có
X-LRS-Timestamplệch quá vài phút so với giờ hiện tại để chống phát lại (ví dụ trên dùng 5 phút). - Lưu secret trong kho bí mật, không đưa vào mã nguồn. Nghi ngờ lộ secret thì xoay vòng ngay bằng
POST /webhooks/{id}/rotate. - Endpoint chỉ nhận HTTPS (cổng 443) và phải là địa chỉ công khai; LRS không đi theo chuyển hướng.