Webhooks

Recevoir des événements

Enregistrez un abonnement de webhook avec un point de terminaison HTTPS et les événements qui vous intéressent. Lorsqu'un événement survient, PIE POST une charge utile JSON vers votre URL et réessaie avec un backoff en cas d'échec. Votre point de terminaison doit répondre 2xx rapidement (dans les 10 secondes) et effectuer tout traitement lourd de façon asynchrone.

Voir la référence des événements de webhook pour la liste complète des types d'événements.

En-têtes de livraison

Chaque livraison porte trois en-têtes :

• X-PIE-Event — le nom de l'événement (par ex. product.published).
• X-PIE-Delivery — un identifiant de livraison unique, utile pour l'idempotence et la déduplication.
• X-PIE-Signature-256 — une signature HMAC du corps brut, préfixée sha256=.

Vérifier la signature

Lorsque vous créez un abonnement, PIE renvoie un secret de signature (affiché une seule fois). PIE signe le corps brut de la requête avec HMAC-SHA256 à l'aide de ce secret et envoie le condensé hexadécimal dans X-PIE-Signature-256. Recalculez-le et comparez avec une vérification à temps constant — rejetez tout ce qui ne correspond pas :

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

// `rawBody` DOIT être les octets exacts reçus — vérifier AVANT JSON.parse.
function verify(rawBody, header, secret) {
  const expected = "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(header ?? "");
  const b = Buffer.from(expected);
  return a.length === b.length && timingSafeEqual(a, b);
}

app.post("/webhooks/pie", (req, res) => {
  const sig = req.header("X-PIE-Signature-256");
  if (!verify(req.rawBody, sig, process.env.PIE_WEBHOOK_SECRET)) {
    return res.sendStatus(401);
  }
  const event = req.header("X-PIE-Event");
  const payload = JSON.parse(req.rawBody);
  // … mettre en file et revenir rapidement …
  res.sendStatus(202);
});