Webhooks

Mit Webhooks reagiert Orblio automatisch auf Ereignisse: Ändert sich etwas — ein Datensatz, eine Seite, eine Datei — schickt Orblio eine signierte HTTP-Nachricht an eine von dir hinterlegte Adresse. So bindest du eigene Programme oder Automatisierungen an.

So funktioniert's

1. Webhook einrichten

   Du hinterlegst eine Ziel-URL, wählst die Ereignisse und (optional) ein Secret. Ein Webhook lässt sich aktiv/inaktiv schalten.

2. Ereignis tritt ein

   Wird z. B. ein Datensatz angelegt, prüft Orblio alle Webhooks, die zu diesem Ereignis passen.

3. Orblio ruft dich auf

   Orblio sendet per POST eine JSON-Nutzlast an deine URL — mit Ereignisname, Zeitstempel und Daten, optional signiert.

4. Dein Endpunkt verarbeitet

   Dein Server prüft die Signatur und tut, was er soll (z. B. einen Cache leeren oder eine Benachrichtigung senden).

Konfiguration eines Webhooks

Jeder Webhook wird zentral gespeichert (in orb_webpage.wData.webhooks) und besteht aus:

Ereignisse

Ereignisnamen folgen dem Muster ressource.aktion. Diese werden ausgelöst:

Platzhalter (Wildcards)

In der events-Liste kannst du gezielt einzelne Ereignisse oder ganze Gruppen abonnieren:

Format der Nutzlast

Orblio sendet einen POST mit Content-Type: application/json und diesem Körper:

{
  "event": "collections.create",
  "timestamp": "2026-07-25T14:03:11+02:00",
  "data": {
    "collection": 3,
    "id": 42,
    "data": { "name": "Maria Muster", "role": "Vorstand" }
  }
}

Gesendet wird mit dem User-Agent Orblio-Webhook/1.0. Die Zustellung ist best-effort mit kurzen Timeouts (Verbindung ~2 s, gesamt ~4 s) und blockiert die CMS-Aktion nie — schlägt ein Aufruf fehl, läuft Orblio normal weiter.

Signatur prüfen

Ist ein secret gesetzt, signiert Orblio den rohen Body mit HMAC-SHA256 und legt das Ergebnis in den Header:

X-Orb-Signature: sha256=<hex-digest>

So verifizierst du auf deinem Server, dass die Nachricht wirklich von deiner Orblio-Installation stammt und unterwegs nicht verändert wurde. Beispiel in PHP:

<?php
$secret  = 'dein-webhook-secret';
$body    = file_get_contents('php://input');
$sig     = $_SERVER['HTTP_X_ORB_SIGNATURE'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $body, $secret);

if (!hash_equals($expected, $sig)) {
    http_response_code(401);
    exit('Ungültige Signatur');
}

$payload = json_decode($body, true);
/* … jetzt sicher verarbeiten … */

const crypto = require('crypto');

function verify(rawBody, header, secret) {
  const expected = 'sha256=' +
    crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(header));
}

Gute Praxis

• Immer HTTPS für die Ziel-URL verwenden.
• Secret setzen und jede Nachricht per Signatur prüfen.
• Schnell antworten (HTTP 2xx) und aufwändige Arbeit in einen Hintergrundprozess auslagern — die Timeouts sind kurz.
• Idempotent verarbeiten: Behandle wiederholte Zustellungen desselben Ereignisses gefahrlos.