Events to other systems

COMPASS calls your systems when what holds changes. The direction matters: COMPASS calls out, your system accepts. You don't have to grant COMPASS access to anything or poll for changes — you give it an address, and COMPASS sends a POST there as soon as something happens.

This is how you attach COMPASS to an automation like n8n, Zapier or Make, to a chat channel, or to a small endpoint of your own. What happens next is your system's decision.

The five events

The two abweichung events fire on the transition only, not on every run that still deviates. A check that finds the same deviation every night for a week sends one event, not seven.

Subscribing

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

The response contains a geheimnis (secret). It is returned exactly this once — afterwards COMPASS only knows its encrypted form, and there is no way to read it back. Store it where your endpoint can find it. If you lose it, deactivate the webhook and create a new one.

The target address must be https:// and must resolve publicly. Addresses on a private network, on localhost or in the link-local range are rejected — both when you create the webhook and again immediately before every delivery, so a name cannot later point at an internal address.

What arrives

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": "your-company", "daten": {"…": "…"}}

Verifying the signature

Always verify the signature before trusting the payload — otherwise anyone who knows your address can feed you events.

It is an HMAC-SHA256 over the timestamp, a dot, and the raw request body: <X-Compass-Zeit>.<body>. The key is your geheimnis.

import hashlib, hmac

def signature_valid(secret: str, sent_at: str, body: bytes, header: str) -> bool:
    mac = hmac.new(secret.encode(), f"{sent_at}.".encode() + body, hashlib.sha256)
    return hmac.compare_digest(f"sha256={mac.hexdigest()}", header)

Two things that go wrong easily: compute over the unmodified body, not over re-serialised JSON — one different space gives a different signature. And compare with compare_digest, not ==.

You should also check the timestamp against your own clock and reject anything too old; that stops a captured delivery from being replayed indefinitely.

Trying it before it matters

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

This queues a delivery with the event ping, regardless of what you subscribed to. Then look at what became of it:

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

Every row names the attempt, the status, the last HTTP code and the last error. This is where you look when something doesn't arrive — not your own logs.

When it fails

If your endpoint does not answer 2xx, COMPASS retries: after one minute, then 5 minutes, 30 minutes, 2, 6, 12, 24 and once more 24 hours. After eight attempts the delivery counts as failed and is not pursued further. The timeout per attempt is 5 seconds, and redirects are not followed.

So accept the delivery quickly and process it afterwards — answer 200 as soon as you have stored it safely, rather than doing the work during the request.

The same delivery can reach you more than once, for instance when your response is lost in transit. Use X-Compass-Zustellung to recognise a delivery you have already processed.

Unsubscribing

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

The webhook stops sending but stays readable together with its deliveries — nothing is ever deleted in COMPASS. GET /webhooks lists the ones you have; the secret is not among them.

If POST /webhooks answers 422

Then outgoing calls are not set up on this installation, and the response says so in plain words. This is not a setting you can change yourself — talk to whoever runs the installation.