Skip to content

Tài liệu kỹ thuật

Tích hợp LRS trong một buổi chiều.

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ệ.

HeaderGiá trị
X-LRS-Delivery-IDMã 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-TimestampThời điểm gửi, tính bằng giây Unix.
X-LRS-Signaturesha256= cộng chữ ký HMAC-SHA256 ở dạng hex.
Content-Typeapplication/json
User-AgentLRS-Webhook/1

Thân yêu cầu

JSON
{
  "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:

Mã
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)

JavaScript
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-Timestamp lệ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.