Zurück zum Hilfecenter

Schnittstelle: Leitfäden

Ereignisse per Webhook empfangen und prüfen

Ziel einrichten, Signatur prüfen, richtig antworten, Wiederholungen verstehen.

Für wen

Entwicklerinnen und Entwickler.

Voraussetzungen

Bestehender Zugang Öffentlich erreichbare HTTPS-Adresse

Schritt für Schritt

  1. 1

    Ziel anlegen

    In der Verwaltung unter „Schnittstelle“ ein Ereignisziel mit Adresse und Ereignisarten anlegen. Verfügbar sind: assessment.approved (Beurteilung freigegeben), action.due (Maßnahme fällig (Vorlauf)), action.overdue (Maßnahme überfällig), barrier_check.failed (Barrierenprüfung nicht bestanden), deadline.approaching (Frist läuft ab). Beim Anlegen wird ein Signaturgeheimnis erzeugt und einmalig angezeigt.

  2. 2

    Zustellung erwarten

    elyph sendet POST mit JSON. Die Kopfzeilen nennen Ereignisart, Zustellkennung und Signatur.

    Zustellung
    POST /elyph/webhook HTTP/1.1
Content-Type: application/json
x-elyph-event: barrier_check.failed
x-elyph-delivery: 4d1c9b7e-…
x-elyph-signature: sha256=9f2c…

{
  "event": "barrier_check.failed",
  "occurred_at": "2026-01-20T08:14:31Z",
  "data": {
    "barrier": { "reference": "BAR-0207", "name": "Zweihandschaltung Presse 3" },
    "result": "failed",
    "findings": "Rechter Taster prellt."
  }
}
  3. 3

    Signatur prüfen

    Die Signatur ist ein HMAC mit SHA-256 über den rohen Textkörper, gebildet mit Ihrem Geheimnis. Prüfen Sie zeitkonstant und vor jeder Verarbeitung.

    Node.js / Express
    import express from "express";
import crypto from "node:crypto";

const app = express();
// Wichtig: den ROHEN Text prüfen, nicht das geparste Objekt.
app.post("/elyph/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const secret = process.env.ELYPH_WEBHOOK_SECRET;
  const expected = "sha256=" + crypto.createHmac("sha256", secret).update(req.body).digest("hex");
  const given = req.header("x-elyph-signature") ?? "";
  const ok =
    given.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected));
  if (!ok) return res.status(401).send("invalid signature");

  const event = JSON.parse(req.body.toString("utf8"));
  enqueue(event);          // schnell annehmen, später verarbeiten
  res.status(200).send("ok");
});
  4. 4

    Schnell antworten

    Antworten Sie innerhalb weniger Sekunden mit einem 2xx-Status und verarbeiten Sie danach. Alles andere gilt als Fehlschlag.

  5. 5

    Wiederholungen einplanen

    Fehlgeschlagene Zustellungen werden nach 1, 5, 30, 120 und 360 Minuten wiederholt. Dieselbe Zustellkennung kann also mehrfach ankommen — verarbeiten Sie sie nur einmal.

    Doppelte abweisen
    const seen = new Set(); // in echten Systemen: Datenbank mit eindeutigem Schlüssel
function enqueue(event, deliveryId) {
  if (seen.has(deliveryId)) return;
  seen.add(deliveryId);
  process(event);
}
  6. 6

    Zustellungen einsehen

    Die Verwaltung zeigt je Ziel die letzten Versuche mit Status, Antwortzeit und Fehlertext. Damit lässt sich prüfen, ob Ihr Endpunkt erreichbar ist.

Ergebnis

Ihre Systeme reagieren in Minuten auf Freigaben, Fristen und nicht bestandene Prüfungen — ohne zu pollen.

Häufige Stolpersteine

  • Signatur nicht prüfen: Der Endpunkt nimmt dann jede fremde Anfrage an.
  • Den geparsten JSON-Text neu serialisieren und prüfen: Die Signatur passt nur zum ursprünglichen Text.
  • Lange Verarbeitung im Endpunkt: Bei Zeitüberschreitung wiederholt elyph dieselbe Nachricht.

Hintergrund

Ereignisse ersetzen kein Abrufen: Nutzen Sie Webhooks für schnelle Reaktionen und einen nächtlichen Abgleich mit `updated_since` als Sicherheitsnetz.

Verwandte Artikel