Webhooks in pixx.io

Was ist ein Webhook?

Ein Webhook ist ein HTTP-Callback: Statt dass dein System pixx.io ständig fragt „Hat sich etwas geändert?“ (Polling), meldet sich pixx.io von selbst, sobald ein definiertes Ereignis eintritt (Push).

Bildlich gesprochen: Polling ist, alle fünf Minuten an der Wohnungstür nachzuschauen, ob Post gekommen ist. Ein Webhook ist die Türklingel — sie meldet sich, wenn's so weit ist.

Funktionsprinzip in pixx.io

Hinter der Ziel-URL kann technisch alles stecken — pixx.io kümmert sich nur um die Zustellung des Events, was danach passiert liegt vollständig bei dir.

Webhook in pixx.io einrichten

1. Öffne die Einstellungen (Zahnrad-Symbol unten links) → Verwaltung → Webhooks.
2. Klicke auf Neuer Webhook.
3. Fülle das Formular „Webhook bearbeiten“ aus (siehe Tabelle unten).
4. Wähle im Bereich Webhook Events die gewünschten Events aus. Events sind in Kategorien gruppiert (z. B. file, collection, comment). Jede Kategorie lässt sich aufklappen; ein ausgefülltes Minus-Symbol an der Kategorie-Checkbox zeigt eine Teilauswahl an.
5. Speichern — der Webhook ist ab sofort aktiv.

Event-Kategorien im Überblick

Die Events sind nach Objekttyp gruppiert. Insgesamt stehen 781 Events in 55 Kategorien zur Verfügung (Stand: aktueller Export). Die größten Kategorien:

Die Kategorie file im Detail

Ein klares Namensschema deckt sowohl den Lebenszyklus einer Datei als auch jede einzelne Metadaten-Änderung granular ab.

fileModified*-Events (Auswahl) — für praktisch jedes Feld gibt es ein eigenes, granulares Event:

Sicherheit: Das Secret & die Signaturprüfung

Ohne Signaturprüfung kann grundsätzlich jeder, der die URL kennt, gefälschte Requests an deinen Endpunkt schicken. Mit einem Secret stellst du sicher, dass eine eingehende Anfrage tatsächlich von pixx.io stammt.

Gängiges, empfohlenes Verfahren (wie bei GitHub, Stripe & Co.):

1. pixx.io berechnet über den Request-Body eine HMAC-SHA256-Signatur unter Verwendung deines Secrets.
2. Die Signatur wird als zusätzlicher Header mitgeschickt.
3. Dein Endpunkt berechnet die Signatur über den empfangenen Rohbody erneut und vergleicht sie zeitkonstant (hash_equals() in PHP, crypto.timingSafeEqual() in Node.js).
4. Nur bei Übereinstimmung wird die Payload als vertrauenswürdig verarbeitet.

Aufbau der Payload (Beispiel)

Jeder Webhook-Aufruf liefert eine JSON-Payload mit Informationen zum Event:

{
  "event": "fileModifiedKeywordsAdded",
  "timestamp": "2026-08-19T10:42:00Z",
  "webhookId": "wh_12345",
  "fileId": 987654,
  "changes": {
    "keywordsAdded": ["Sommer", "Kampagne2026"]
  },
  "triggeredBy": {
    "userId": 42,
    "userName": "c.trautbeck"
  }
}

Best Practices für den Empfänger

• HTTPS verwenden — Klartext-HTTP-Endpunkte sind ein Sicherheitsrisiko.
• Signatur zuerst prüfen, bevor die Payload überhaupt verarbeitet wird.
• Schnell antworten: Empfang zügig mit 2xx bestätigen, Verarbeitung asynchron auslagern (Queue, Background-Job).
• Idempotent verarbeiten: Events können theoretisch doppelt zugestellt werden — eindeutige IDs helfen bei der Duplikaterkennung.
• Granular abonnieren: Lieber gezielte fileModified*-Events als die gesamte Kategorie file.
• Logging & Monitoring: Eingehende Events und Fehlerraten protokollieren.
• Massenoperationen einplanen: Ein Bulk-Upload kann in kurzer Zeit sehr viele Events auslösen — Queue statt synchroner Verarbeitung.

Anwendungsfälle

Kombination mit Automatisierungsplattformen

Für viele Anwendungsfälle ist gar kein eigener Server nötig — Automatisierungsplattformen übernehmen Empfang, Logik und Rückruf:

• Make (ehemals Integromat): pixx.io bietet eine eigene Make-App mit vorgefertigten Modulen. Alternativ lässt sich auch der generische „Custom Webhook“-Trigger von Make direkt als Webhook-URL in pixx.io eintragen.
• Zapier / n8n: Beide bieten einen generischen Webhook-Trigger mit eindeutiger URL. Diese URL wird 1:1 in das URL-Feld des pixx.io-Webhooks eingetragen — danach lässt sich mit Filtern, Routern und HTTP-Modulen die gewünschte Logik bauen, inklusive Rückruf an die pixx.io API.

Der Vorteil: Filterung nach Event-Typ, Datenumformung und Fehlerbehandlung lassen sich visuell konfigurieren, ganz ohne eigenen Code.

Eigener Skript-Empfänger (PHP)

<?php
// webhook-receiver.php
$secret  = getenv('PIXXIO_WEBHOOK_SECRET');
$payload = file_get_contents('php://input');
$signatureHeader = $_SERVER['HTTP_X_PIXXIO_SIGNATURE'] ?? '';
$expectedSignature = hash_hmac('sha256', $payload, $secret);
if (!hash_equals($expectedSignature, $signatureHeader)) {
    http_response_code(401);
    exit('Invalid signature');
}
// Payload sofort bestätigen, Verarbeitung asynchron auslagern
http_response_code(200);
$data = json_decode($payload, true);
switch ($data['event'] ?? '') {
    case 'fileCreated':
        // z. B. Job in eine Queue legen: KI-Verarbeitung anstoßen
        break;
    case 'fileModifiedKeywordsAdded':
        // z. B. eigenen Suchindex aktualisieren
        break;
}

Der Kreis schließt sich: Zurückschreiben über die API

Ein Webhook allein liefert nur Informationen — die eigentliche Automatisierung entsteht erst im Zusammenspiel mit der pixx.io REST-API. Typischer Ablauf am Beispiel einer automatischen Alt-Text-Generierung:

1. Trigger: fileCreated feuert nach einem Upload.
2. Kontext holen: Das Skript lädt bei Bedarf weitere Datei-Informationen über die API nach.
3. Verarbeitung: Ein externer KI-Dienst generiert Alt-Text bzw. Schlagworte.
4. Rückschreiben: Das Skript aktualisiert die Datei in pixx.io über die API — Custom-Metadata-Feld, Schlagworte oder Kommentar.

Für das Rückschreiben stehen je nach Objekt eigene API-Endpunkte bereit (Dateien, Sammlungen, Schlagworte, Custom-Metadaten, externe Freigaben u. v. m.) — die vollständige, aktuelle Referenz inklusive Authentifizierung findest du in der API-Dokumentation.

Checkliste vor dem Go-Live

• Endpunkt ist über HTTPS öffentlich erreichbar
• Secret ist gesetzt, Signaturprüfung ist implementiert
• Nur die tatsächlich benötigten Events sind abonniert
• Antwort erfolgt schnell (2xx), Verarbeitung läuft asynchron
• Duplikate/Wiederholungen werden idempotent behandelt
• Logging und Monitoring sind aktiv
• Vor dem Rollout mit einem einzelnen Test-Event geprüft

Weiterführende Links

• pixx.io API-Dokumentation →
• pixx.io SDK →
• pixx.io Make-Integration →
• pixx.io Helpcenter →

Anhang: Vollständige Event-Liste

Alle 781 Events in 55 Kategorien — durchsuchbar und filterbar. Für die Weiterverarbeitung steht die komplette Liste auch als CSV-Datei zum Download bereit.