Webhooks

Ereignisse empfangen

Registrieren Sie ein Webhook-Abonnement mit einem HTTPS-Endpunkt und den Ereignissen, die Sie interessieren. Wenn etwas passiert, sendet PIE per POST eine JSON-Nutzlast an Ihre URL und wiederholt bei Fehlschlag mit Backoff. Ihr Endpunkt sollte schnell (innerhalb von 10 Sekunden) mit 2xx antworten und aufwändige Arbeit asynchron erledigen.

Die vollständige Liste der Ereignistypen finden Sie in der Webhook-Ereignisse-Referenz.

Zustellheader

Jede Zustellung trägt drei Header:

• X-PIE-Event — der Ereignisname (z. B. product.published).
• X-PIE-Delivery — eine eindeutige Zustell-ID, nützlich für Idempotenz und Deduplizierung.
• X-PIE-Signature-256 — eine HMAC-Signatur des rohen Bodys, mit sha256= präfixiert.

Die Signatur prüfen

Wenn Sie ein Abonnement anlegen, gibt PIE ein Signaturgeheimnis zurück (einmal angezeigt). PIE signiert den rohen Anfrage-Body mit HMAC-SHA256 unter Verwendung dieses Geheimnisses und sendet den Hex-Digest in X-PIE-Signature-256. Berechnen Sie ihn neu und vergleichen Sie mit einer konstantzeitigen Prüfung — lehnen Sie alles ab, was nicht übereinstimmt:

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

// `rawBody` MUSS exakt die empfangenen Bytes sein — VOR JSON.parse prüfen.
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);
  // … einreihen und schnell zurückkehren …
  res.sendStatus(202);
});