Webhooks, Zähler-Regeln und Rezepte

Webhooks

Webhooks drehen die Richtung um: Vormerk meldet ein Ereignis an Ihre Adresse, sobald es eintritt.

Einrichten. Team → API → Webhooks → Neuer Empfänger: Bezeichnung, Adresse (https, öffentlich erreichbar), gewünschte Ereignisse und optional ein Bereich (Standorte, Arten, Objekte). Nach dem Speichern zeigt die Seite das Signaturgeheimnis (whsec_…). Mit Testmeldung senden prüfen Sie die Verbindung.

Ereignisse

Aufbau einer Meldung (POST, JSON):

{
  "id": "6f5c…",
  "type": "incident.created",
  "created_at": "2026-10-15T08:30:12+00:00",
  "data": {"id": 41, "ref": "K7M2QX4R", "title": "Druckabfall", "status": "new",
           "priority": "high", "object_id": 17, "external_ref": "ALARM-4711"}
}

Die Daten sind schlank gehalten und enthalten keine Namen von Personen. Alles Weitere holen Sie bei Bedarf über die Schnittstelle ab.

Kopfzeilen. X-Vormerk-Event, X-Vormerk-Delivery (Kennung der Zustellung, gleich bei Wiederholungen: nützlich zum Entdoppeln), X-Vormerk-Timestamp (Sekunden), X-Vormerk-Signature.

Signatur prüfen. Die Signatur ist v1= plus der HMAC-SHA256 über <Timestamp>.<Rumpf> mit dem Geheimnis. Verwenden Sie den unveränderten Rumpf, nicht das neu serialisierte JSON, und lehnen Sie Zeitstempel ab, die mehr als fünf Minuten abweichen.

import hashlib, hmac, time


def pruefen(geheimnis: str, rumpf: bytes, kopf: dict) -> bool:
    ts = int(kopf["X-Vormerk-Timestamp"])
    if abs(time.time() - ts) > 300:
        return False
    erwartet = (
        "v1=" + hmac.new(geheimnis.encode(), f"{ts}.".encode() + rumpf, hashlib.sha256).hexdigest()
    )
    return hmac.compare_digest(erwartet, kopf["X-Vormerk-Signature"])

const crypto = require("crypto");
function pruefen(geheimnis, rumpf /* Buffer */, kopf) {
  const ts = Number(kopf["x-vormerk-timestamp"]);
  if (Math.abs(Date.now() / 1000 - ts) > 300) return false;
  const erwartet = "v1=" + crypto.createHmac("sha256", geheimnis)
    .update(`${ts}.`).update(rumpf).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(erwartet), Buffer.from(kopf["x-vormerk-signature"]));
}

Antworten und Wiederholungen. Antworten Sie mit einem 2xx innerhalb von 10 Sekunden. Alles andere gilt als Fehlschlag. Vormerk wiederholt dann nach 1 Minute, 5 Minuten, 30 Minuten, 2 Stunden und 12 Stunden und gibt danach auf. Bei 20 aufgegebenen Zustellungen in Folge schaltet es den Empfänger ab (Hinweis auf der Seite; zum Einschalten speichern Sie ihn mit gesetztem Haken „Aktiv“). Die Zustellungen der letzten Tage sehen Sie auf der Seite des Empfängers, einzelne lassen sich dort sofort wiederholen. Zustellprotokolle werden nach 14 Tagen gelöscht.

Gut zu wissen. Meldungen können doppelt oder in anderer Reihenfolge eintreffen: Entdoppeln Sie über X-Vormerk-Delivery und lesen Sie bei Bedarf den aktuellen Stand nach. Interne und lokale Adressen sind nicht erlaubt, ebenso Weiterleitungen. Geheimnis erneuern macht das alte sofort ungültig; tragen Sie das neue zuerst bei Ihrem Empfänger ein.

Zähler-Regeln

Maschinen → Zähler-Regeln. Eine Regel gehört zum Zähler einer Maschine und löst bei einem Grenzwert etwas aus.

Die Regel prüft jeden neuen Zählerstand, egal ob er aus der Oberfläche, der API oder einer Wartung kommt. Springt der Zähler über mehrere Vielfache, löst sie einmal aus. Ändern Sie Wert oder Art, zählt sie ab dem aktuellen Stand neu; Neu zählen macht das von Hand.

Regel oder Wartungsplan? Regelmäßige Wartungen nach Zählerstand gehören in den Wartungsplan (Zählerintervall): Der Plan setzt sich nach jeder durchgeführten Wartung selbst fort und erscheint in den Fälligkeiten und Erinnerungen. Regeln sind für Besonderes da, etwa einmalige Grenzen, Warnungen und Meldungen an andere Systeme. Tragen Sie dieselbe Grenze nicht in beiden ein, sonst entstehen zwei Aufgaben.

Rezepte

Gateway meldet Betriebsstunden. Schlüssel mit meters:write, Bereich auf die Maschine(n) des Gateways, Adressliste auf die feste Adresse des Gateways. Das Gateway sendet alle paar Minuten einen Sammelabruf mit Idempotency-Key. Eine Zähler-Regel „alle 500 h → Wartungsaufgabe“ oder der Plan mit Zählerintervall kümmert sich um den Rest.

Alarm aus dem Leitsystem wird zur Störung. Schlüssel mit incidents:create. Das Leitsystem ruft POST /incidents mit external_ref = Alarmnummer auf. Wiederholte Alarme erzeugen keine weitere Störung. Meldet das Leitsystem „Alarm quittiert“, setzen Sie mit incidents:update den Status.

Nächtlicher Abgleich mit dem ERP. Schlüssel mit objects:read und objects:write. Ein Skript ruft je Anlage PUT /machines/by-external-id/{kennung} auf. Standorte legt es vorher mit POST /locations an. Löschungen macht die Schnittstelle absichtlich nicht; ausgemusterte Maschinen setzen Sie in Vormerk auf „Ausgemustert“.

Dashboard im Leitstand. Schlüssel mit maintenance:read und incidents:read. Fragen Sie GET /due und GET /incidents?status=open ab. Besser als Abfragen im Minutentakt: ein Webhook auf incident.created und maintenance.due.

Automatisierung mit n8n, Zapier oder Make. Ein Webhook-Empfänger auf die Adresse des Dienstes, Ereignisse nach Bedarf. Für Aktionen nehmen Sie einen HTTP-Baustein mit dem Schlüssel im Kopf Authorization.

Fehlersuche