Reference ng server

Lia ay ipapalista sa iyong server kung ang isang charge ay bayad o refund at kung ang isang reward ay binayaran, na nakasiguro sa iyong webhook secret. Ano ang ipinadala, kung paano suriin ang signature, at kung paano gumagana ang mga retry.

#Pag-set up ng isang bagay

Bigyan ang koponan ng Lia ng isang https address sa iyong server, at panatilihin ang webhook signing secret (whsec_…) na kasama sa iyong mga key. Lia pagkatapos ay nagpapadala ng isang POST nasa doon kapag nangyari ang anumang bagay sa iyong app.

Ang isang webhook ay isang nudge, hindi ang katotohanan: suriin ang API bago magawa ang isang bagay (para sa isang bayad, GET /charges/:id. At hindi ito'hindi maaabot batay lamang sa webhooks; ang iyong pahina ay maaari ring sabihin sa iyong server (tingnan Bilhin ang isang item).

#Ano's sent

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
  }
}

#Uri

Suriin data.mode (o ang singil's mode) kaya ang mga test event ay walang nagbibigay ng anumang tunay. Maaaring idagdag ang mas maraming mga uri: i-ignore ang mga uri na hindi mo nakikita'hindi alam at sumagot 200.

#Pagsusuri sa signature

Bawat webhook ay may Lia-Signature ang header, t=<seconds>,v1=<signature>. Ang signature ay HMAC SHA-256, sa hex, ng mga segundo, isang punto, at ang raw body, key sa iyong buong webhook secret (kasama ang whsec_):

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

Suriin ito laban sa raw body nang eksaktong tulad ng nanggaling ito, bago ito i-parse, at i-override ang webhooks na higit sa ilang minuto ang gulang.

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;
}

Pamahalaan ang mga webhook may isang kumpletong handler.

#Mga sagot at pagsubok muli

• Sagot sa anumang 2xx estado, nang mabilis. Gawin ang mabagal na trabaho pagkatapos magbigay ng sagot.
• Kung ang iyong server ay hindi't sagot 2xx (o maaaring't maabot), Lia subukan ulit agad. Pagkatapos nito, ang webhook ay hindi'hindi maaabot ipadala muli.
• Kaya maaaring mawala ang mga webhook, at maaaring dumating dalawa. Gawaing maaaring mag-uto nang dalawa (key ito sa charge id o sa reward key), at may iba pang paraan para makasunod, tulad ng Lia.charges() kapag ang manlalaro ay buksan ang iyong app.

#Ang iyong lihim

Ang iyong webhook secret ay nagbabago kapag ang iyong mga key ay ginawa ulit. Panatilihin ito sa iyong server, kasama ang iyong key.

Awtomatikong isinalin. Ang English ay ang source of truth. Basahin sa Ingles