Référence du serveur

Webhooks

Copier la page

Lia informe votre serveur lorsqu'un paiement est effectué ou remboursé et lorsqu'une récompense est versée, signé avec votre secret de webhook. Ce qui est envoyé, comment vérifier la signature, et comment fonctionnent les réessais.

#Configurer un

Donnez à l'équipe Lia une adresse https sur votre serveur, et gardez le secret de signature du webhook (whsec_…) qui accompagnaient vos clés. Lia envoie alors un POST là quand quelque chose se produit dans votre application.

Un webhook est un poussée, pas la vérité : vérifiez avec API avant d'agir (pour une charge, GET /charges/:id). Et ne'ne se fie pas uniquement aux webhooks ; votre page peut également informer votre serveur (voir Vendre un article).

#Quoi'les envoyés

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

Champ	Type
`type`	chaîne	Ce qui s'est passé (ci-dessous).
`app`	chaîne	Votre identifiant d'application
`at`	nombre	Quand il a été envoyé, en millisecondes depuis 1970.
`data`	objet	Ce qu''concerne.

#Types

Type	Quand	`data`
`charge.paid`	Une personne a payé sur Lia'la feuille de paiement, en test ou en production.	Le frais, avec `status: "paid"`
`charge.refunded`	Vous avez remboursé une charge.	La charge, avec `status: "refunded"`
`reward.paid`	Vous avez versé une récompense depuis votre pool, en test ou en production.	`{ key, playerId, amount, reason, mode }`

Vérifier data.mode (ou la charge's mode) donc les événements de test ne donnent jamais rien de réel. D'autres types peuvent être ajoutés : ignorez les types que vous ne connaissez pas'ne pas savoir et répondre 200.

#Vérification de la signature

Chaque webhook a une Lia-Signature l'en-tête, t=<seconds>,v1=<signature>. La signature est HMAC SHA-256, en hexadécimal, des secondes, un point, et le corps brut, clé avec votre secret de webhook entier (y compris whsec_):

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

Vérifiez-le contre le corps brut exactement comme il est arrivé, avant de le parser, et refusez les webhooks plus anciens de quelques minutes.

Node.js

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

Cloudflare Workers, Deno, Bun

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

Gérer les webhooks a un gestionnaire complet.

#Réponses et tentatives

Répondez avec n'importe quel 2xx état, rapidement. Faites le travail lent après avoir répondu.
Si votre serveur n''t répondre 2xx (ou peut'ne pas être atteint), Lia tente une nouvelle fois immédiatement. Après cela, le webhook ne'ne peut être envoyé à nouveau.
Les webhooks peuvent être manqués, et peuvent arriver deux fois. Rendez votre gestionnaire sûr de s'exécuter deux fois (utilisez l'identifiant de la charge ou la clé de la récompense), et disposez d'une autre méthode pour rattraper, telle que Lia.charges() quand le joueur ouvre votre application.

#Votre secret

Votre secret de webhook change chaque fois que vos clés sont recrées. Gardez-le sur votre serveur, à côté de votre clé.

Traduit automatiquement. L'anglais est la source de vérité. Lire en anglais