Tham chiếu máy chủ

Lia thông báo cho máy chủ của bạn khi một khoản thanh toán được thanh toán hoặc hoàn tiền và khi một phần thưởng được trả, được ký bằng bí mật webhook của bạn. Những gì được gửi, cách kiểm tra chữ ký và cách xử lý lại.

#Thiết lập một cái

Cho đội Lia một địa chỉ https trên máy chủ của bạn, và giữ bí mật chữ ký webhook (whsec_…) mà bạn nhận được cùng với khóa. Lia sau đó gửi một POST có mặt khi có điều gì đó xảy ra trong ứng dụng của bạn.

Một webhook là một nhắc nhở, không phải sự thật: kiểm tra với API trước khi hành động (đối với một khoản thanh toán, GET /charges/:id). Và không'dựa vào webhook riêng; trang web của bạn cũng có thể thông báo cho máy chủ của bạn (xem Bán một vật phẩm).

#Cái gì'được gửi

POST /lia/webhook
Content-Type: application/json
Lia-Signature: t=1761998400,v1=5f2c8a…

{
  "type": "charge.paid",
  "app": "your-app",
  "at": 1761998400123,
  "data": {
    "id": "ch_9b1f4c2e7a0d5b8f3e6a1c4d",
    "playerId": "p_3f9c0a6d1b2e4f5a6b7c",
    "productId": "extra-lives",
    "amount": 5,
    "status": "paid",
    "mode": "live",
    "createdAt": 1761998400000,
    "deliveredAt": null,
    "refundedAt": null
  }
}

#Loại

Kiểm tra data.mode (hoặc khoản phí's mode) nên các sự kiện thử nghiệm không bao giờ cấp phát gì thực sự. Có thể thêm nhiều loại hơn: bỏ qua các loại bạn không'biết và trả lời 200.

#Kiểm tra chữ ký

Mỗi webhook có một Lia-Signature tiêu đề, t=<seconds>,v1=<signature>. Chữ ký là HMAC SHA-256, ở dạng hex, của các giây, một dấu chấm, và nội dung thô, được khóa bằng bí mật webhook toàn bộ của bạn (bao gồm whsec_):

v1 = hex(HMAC_SHA256(key = "whsec_…", message = t + "." + rawBody))

Kiểm tra nó với cơ thể gốc ngay khi nó đến, trước khi phân tích, và từ chối các webhooks quá vài phút.

import { createHmac, timingSafeEqual } from "node:crypto";

export function liaWebhook(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries((header ?? "").split(",").map((part) => part.split("=")));
  const t = Number(parts.t);
  if (!t || !parts.v1) return null;
  if (Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return null;
  const expected = Buffer.from(createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex"));
  const given = Buffer.from(parts.v1);
  if (expected.length !== given.length || !timingSafeEqual(expected, given)) return null;
  return JSON.parse(rawBody);
}

export async function liaWebhook(request, secret, toleranceSeconds = 300) {
  const rawBody = await request.text();
  const parts = Object.fromEntries((request.headers.get("Lia-Signature") ?? "").split(",").map((part) => part.split("=")));
  const t = Number(parts.t);
  if (!t || !parts.v1 || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return null;
  const key = await crypto.subtle.importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["verify"]);
  const signature = new Uint8Array(parts.v1.match(/../g).map((byte) => parseInt(byte, 16)));
  const ok = await crypto.subtle.verify("HMAC", key, signature, new TextEncoder().encode(`${t}.${rawBody}`));
  return ok ? JSON.parse(rawBody) : null;
}

Xử lý webhook có một xử lý đầy đủ.

#Trả lời và thử lại

• Trả lời bằng bất kỳ 2xx trạng thái, nhanh chóng. Làm việc chậm sau khi trả lời.
• Nếu máy chủ của bạn không't câu trả lời 2xx (hoặc có thể't được truy cập), Lia sẽ thử lại ngay lập tức. Sau đó, webhook không phải'được gửi lại.
• Vì vậy, các webhook có thể bị bỏ lỡ và có thể đến hai lần. Hãy đảm bảo xử lý của bạn an toàn để chạy hai lần (dựa trên id hóa đơn hoặc khóa phần thưởng), và có một cách khác để bắt kịp, ví dụ như Lia.charges() khi người chơi mở ứng dụng của bạn.

#Mật khẩu của bạn

Mật khẩu webhook của bạn thay đổi mỗi khi bạn tạo lại khóa. Giữ nó trên máy chủ của bạn, bên cạnh khóa của bạn.

Được dịch tự động. Tiếng Anh là nguồn tin cậy. Đọc bằng tiếng Anh