Ereignisse nach außen

COMPASS meldet sich bei euren Systemen, wenn sich ändert, was gilt. Die Richtung ist wichtig: COMPASS ruft raus, euer System nimmt an. Ihr braucht dafür keinen Zugang zu COMPASS einzurichten und nichts abzufragen — ihr gebt eine Adresse an, und COMPASS schickt dorthin einen POST, sobald etwas passiert.

Damit hängt ihr COMPASS an eine Automatisierung wie n8n, Zapier oder Make, an einen Chat-Kanal oder an einen eigenen kleinen Endpunkt. Was danach passiert, entscheidet euer System.

Die fünf Ereignisse

Die beiden abweichung-Ereignisse feuern nur beim Wechsel, nicht bei jedem Lauf, der weiterhin abweicht. Ein Prüfweg, der eine Woche lang jede Nacht dieselbe Abweichung findet, schickt ein Ereignis, nicht sieben.

Anmelden

curl -sS -X POST "$COMPASS_URL/webhooks" \
  -H "X-Compass-Key: $COMPASS_KEY_RW" -H "Content-Type: application/json" \
  -d '{
        "url": "https://eure-automatisierung.example/compass",
        "ereignisse": ["regel.gesetzt", "regel.abgeloest"]
      }'

Die Antwort enthält ein geheimnis. Es wird genau dieses eine Mal ausgeliefert — danach kennt COMPASS nur noch seine verschlüsselte Form, und es gibt keinen Weg, es wieder auszulesen. Leg es dort ab, wo euer Endpunkt es findet. Habt ihr es verloren, meldet ihr den Webhook ab und legt einen neuen an.

Die Zieladresse muss https:// sein und öffentlich auflösen. Adressen im privaten Netz, auf localhost oder im Link-lokalen Bereich werden abgelehnt — beim Anlegen und noch einmal unmittelbar vor jedem Versand, damit ein Name nicht nachträglich auf eine interne Adresse zeigen kann.

Was ankommt

POST /compass HTTP/1.1
Content-Type: application/json
X-Compass-Signatur: sha256=4f1c…
X-Compass-Zeit: 1758380400
X-Compass-Zustellung: 812

{"id": 812, "ereignis": "regel.gesetzt", "zeitpunkt": "2026-09-20T16:20:00Z",
 "kunde": "eure-firma", "daten": {"…": "…"}}

Die Signatur prüfen

Prüfe immer die Signatur, bevor ihr dem Inhalt glaubt — sonst kann jeder, der eure Adresse kennt, euch Ereignisse unterschieben.

Gebildet wird sie als HMAC-SHA256 über den Zeitstempel, einen Punkt und den rohen Anfragekörper: <X-Compass-Zeit>.<body>. Schlüssel ist euer geheimnis.

import hashlib, hmac

def signatur_gueltig(geheimnis: str, zeit: str, body: bytes, kopf: str) -> bool:
    mac = hmac.new(geheimnis.encode(), f"{zeit}.".encode() + body, hashlib.sha256)
    return hmac.compare_digest(f"sha256={mac.hexdigest()}", kopf)

Zwei Dinge, die leicht schiefgehen: rechne über den unveränderten Körper, nicht über neu zusammengesetztes JSON — ein anderes Leerzeichen ergibt eine andere Signatur. Und vergleiche mit compare_digest, nicht mit ==.

Den Zeitstempel solltet ihr zusätzlich gegen eure Uhr prüfen und alles ablehnen, was zu alt ist; damit lässt sich eine einmal mitgeschnittene Zustellung nicht beliebig oft wiederholen.

Ausprobieren, bevor es ernst wird

curl -sS -X POST "$COMPASS_URL/webhooks/$ID/test" -H "X-Compass-Key: $COMPASS_KEY_RW"

Das schickt eine Zustellung mit dem Ereignis ping — unabhängig davon, was ihr abonniert habt. Danach seht ihr nach, was daraus wurde:

curl -sS "$COMPASS_URL/webhooks/$ID/zustellungen?limit=50" -H "X-Compass-Key: $COMPASS_KEY_RO"

Jede Zeile nennt Versuch, Status, den letzten HTTP-Code und den letzten Fehler. Das ist die Stelle, an der ihr nachseht, wenn etwas nicht ankommt — nicht eure eigenen Logs.

Wenn es schiefgeht

Antwortet euer Endpunkt nicht mit 2xx, versucht COMPASS es erneut: nach einer Minute, dann 5 Minuten, 30 Minuten, 2, 6, 12, 24 und noch einmal 24 Stunden. Nach acht Versuchen gilt die Zustellung als gescheitert und wird nicht weiter verfolgt. Das Zeitlimit je Versuch ist 5 Sekunden, Weiterleitungen werden nicht verfolgt.

Nimm die Zustellung also schnell an und arbeite sie hinterher ab — antworte mit 200, sobald ihr sie sicher abgelegt habt, statt während der Anfrage zu verarbeiten.

Dieselbe Zustellung kann euch mehr als einmal erreichen, etwa wenn eure Antwort unterwegs verloren geht. Nutze X-Compass-Zustellung, um eine bereits verarbeitete Zustellung wiederzuerkennen.

Abmelden

curl -sS -X POST "$COMPASS_URL/webhooks/$ID/deaktivieren" -H "X-Compass-Key: $COMPASS_KEY_RW"

Der Webhook hört auf zu senden, bleibt aber samt seiner Zustellungen lesbar — gelöscht wird in COMPASS nichts. Welche Webhooks ihr habt, zeigt GET /webhooks; das Geheimnis ist dort nicht dabei.

Wenn POST /webhooks mit 422 antwortet

Dann sind ausgehende Aufrufe auf dieser Installation nicht eingerichtet, und die Antwort sagt das im Klartext. Das ist keine Einstellung, die ihr selbst ändern kannst — wende euch an die Person, die diese Installation betreibt.