Directus Webhooks: Der Praxisguide für eingehende und ausgehende Trigger

Webhooks gehören zu den wichtigsten Integrationsmechanismen moderner Software-Architekturen. Statt regelmäßig nach Änderungen zu fragen, werden Systeme automatisch informiert, sobald ein Ereignis eintritt.

Directus unterstützt sowohl eingehende Webhooks als auch ausgehende Webhook-Requests. Dadurch lässt sich die Plattform nahtlos mit ERP-Systemen, Zahlungsanbietern, CRM-Lösungen, GitHub, Slack oder beliebigen anderen APIs verbinden.

In diesem Leitfaden lernen Sie:

  • wie eingehende Webhooks funktionieren
  • wie Directus externe Systeme aufrufen kann
  • wie Sie Webhooks absichern
  • wie Sie Fehler analysieren und debuggen
  • wann ein Webhook-Trigger sinnvoller ist als ein Event Hook

Für die Grundlagen empfiehlt sich zunächst die Directus Flows Anleitung.

Webhook-Modelle in Directus

Directus unterstützt zwei grundlegend unterschiedliche Kommunikationsrichtungen.

Eingehend – externe Systeme rufen Directus auf

Ein externes System sendet Daten an Directus.

Typische Beispiele:

  • Stripe meldet erfolgreiche Zahlungen
  • GitHub meldet neue Pull Requests
  • ERP-System meldet Lagerbestände
  • CRM-System meldet neue Leads

Der eingehende Request startet einen Flow.

Ausgehend – Directus ruft externe Systeme auf

Ein Ereignis innerhalb von Directus löst einen HTTP-Request aus.

Typische Beispiele:

  • Slack-Nachricht versenden
  • CRM aktualisieren
  • Ticket in Jira anlegen
  • Bestellung an ERP übertragen

Dies erfolgt über die Operation Webhook Request URL.

 

Wann welches Modell?

Situation

Lösung

Externes System meldet Ereignisse

Eingehender Webhook

Directus soll ein anderes System informieren

Ausgehender Webhook

Datenbankänderungen innerhalb Directus

Event Hook

Regelmäßige Ausführung

Schedule Trigger

 

Eingehende Webhooks einrichten

Neuen Flow mit Webhook-Trigger erstellen

Im Flow Builder:

Trigger → Webhook

Nach dem Speichern erzeugt Directus automatisch eine eindeutige URL.

Beispiel:

https://example.com/flows/trigger/customer-created

Intern verwendet Directus das Muster:

/flows/trigger/:webhook-id

Die Webhook-ID wird automatisch vergeben oder kann benutzerfreundlich definiert werden.

Diese URL kann anschließend in Stripe, GitHub, SAP oder jedem anderen System hinterlegt werden.

GET oder POST wählen

Directus unterstützt unterschiedliche HTTP-Methoden.

GET

Geeignet für:

  • einfache Trigger
  • Tests
  • Statusabfragen

POST

Empfohlen für:

  • JSON-Payloads
  • ERP-Integrationen
  • Zahlungsanbieter
  • produktive Systeme

Die meisten Integrationen verwenden POST.

Asynchron schalten

Eine häufig übersehene Option ist:

Asynchronous Execution

Wenn aktiviert:

  • Directus antwortet sofort mit HTTP 200
  • der Flow läuft im Hintergrund weiter

Vorteile:

  • bessere Performance
  • geringere Timeout-Gefahr
  • bessere Benutzererfahrung

Für nahezu alle produktiven Webhooks ist dies die empfohlene Einstellung.

Response Body definieren

Directus kann individuelle Antworten zurückgeben.

Beispiel:

{
"status": "received"
}

Dadurch weiß das externe System, dass die Verarbeitung erfolgreich gestartet wurde.

 

Sicherheit

Webhooks sind öffentlich erreichbare Endpunkte.

Daher sollte Sicherheit immer berücksichtigt werden.

Secret-Header validieren

Der einfachste Schutz:

Ein geheimer Header wird mitgesendet.

Beispiel:

X-Webhook-Secret: my-secret-key

Im Flow wird geprüft:

if ($trigger.headers["x-webhook-secret"] !== "my-secret-key") {
throw new Error("Unauthorized");
}

Nur Requests mit dem richtigen Secret werden verarbeitet.

Stripe-Signatur verifizieren

Stripe verwendet kryptographische Signaturen.

Beispiel einer Run-Script-Operation:

const signature = $trigger.headers[„stripe-signature“];

if (!signature) {
throw new Error("Missing Stripe Signature");
}

return {
verified: true
};

In produktiven Umgebungen sollte zusätzlich die offizielle Stripe-Signaturprüfung implementiert werden.

IP-Allow-List nutzen

Wenn möglich:

  • Stripe-IP-Ranges
  • ERP-IP-Adressen
  • Unternehmensnetzwerke

auf Reverse-Proxy-Ebene einschränken.

Geeignete Werkzeuge:

  • Nginx
  • Traefik
  • Cloudflare
  • AWS WAF

Rate Limiting

Öffentliche Webhook-Endpunkte sollten gegen Missbrauch geschützt werden.

Empfohlene Begrenzungen:

  • 10 Requests/Sekunde
  • Burst-Limits
  • automatische Sperren bei Angriffen

Rate Limiting erfolgt normalerweise auf Proxy-Ebene und nicht in Directus selbst.

Ausgehende Webhooks mit “Webhook Request URL”

Die Operation Webhook Request URL ermöglicht HTTP-Aufrufe aus Directus heraus.

Konfiguration der Operation

Wichtige Einstellungen:

  • URL
  • Methode
  • Header
  • Payload
  • Timeout

Beispiel:

POST https://hooks.slack.com/services/...

Header definieren

Typischer JSON-Request:

{
"Content-Type": "application/json"
}

API-Authentifizierung:

{
"Authorization": "Bearer TOKEN"
}

Payload Templates

Die Payload kann dynamisch aus der Data Chain erzeugt werden.

Beispiel:

{
"customer": "{{ $trigger.payload.company }}",
"email": "{{ $trigger.payload.email }}"
}

Dadurch können Daten aus vorherigen Operations direkt verwendet werden.

Fehlerbehandlung

Externe APIs können fehlschlagen.

Empfehlungen:

  • Statuscodes prüfen
  • Fehler protokollieren
  • Retry-Mechanismen nutzen
  • kritische Fehler speichern

 

Praxisbeispiele

Stripe-Event empfangen

Ablauf:

  1. Stripe sendet Event
  2. Webhook-Trigger startet
  3. Signatur prüfen
  4. Bestellung aktualisieren
  5. Bestätigung speichern

Typische Events:

  • payment_intent.succeeded
  • invoice.paid
  • customer.created

Slack-Nachricht senden

Flow:

  • neuer Kunde erstellt
  • Kundendaten lesen
  • Nachricht generieren
  • Slack-WebHook aufrufen

Payload:

{
"text": "Neuer Kunde registriert."
}

GitHub Issue erstellen

Flow:

  • Fehlerdatensatz angelegt
  • Priorität prüfen
  • GitHub API aufrufen
  • Issue erzeugen

So entsteht automatisch ein Ticket-System.

 

Migration von den alten Webhook-Einstellungen

Frühere Directus-Versionen boten separate Webhook-Konfigurationen.

Diese gelten heute als veraltet.

Warum die alte Lösung deprecated ist

Nachteile:

  • keine Data Chain
  • keine Bedingungen
  • keine komplexen Workflows
  • schlechte Erweiterbarkeit

Flows lösen diese Probleme vollständig.

Schritt-für-Schritt-Migration

  1. Alten Webhook identifizieren
  2. Neuen Flow anlegen
  3. Webhook Trigger konfigurieren
  4. Logik in Operations abbilden
  5. Testen
  6. Alten Webhook deaktivieren

 

Best Practices für produktive Webhooks

Immer asynchron arbeiten

Synchron nur bei echten Echtzeit-Anforderungen.

Ansonsten:

  • schneller
  • stabiler
  • weniger Timeouts

Logging einbauen

Eine zusätzliche Log-Operation am Ende jedes Flows erleichtert Debugging erheblich.

Speichern Sie:

  • Zeitpunkt
  • Payload
  • Status
  • Fehlermeldung

Payloads versionieren

Externe Systeme ändern sich.

Empfehlung:

{
"version": "v1"
}

Dadurch bleiben Integrationen langfristig wartbar.

 

Fazit

Webhooks sind die wichtigste Integrationsschnittstelle in Directus.

Eingehende Webhooks erlauben es externen Systemen, Ereignisse an Directus zu melden. Ausgehende Webhook-Requests machen Directus selbst zum aktiven Teilnehmer in Ihrer Systemlandschaft.

Für produktive Umgebungen sollten Sie drei Punkte immer berücksichtigen:

  • Secret-Header oder Signaturen verwenden
  • asynchrone Verarbeitung aktivieren
  • Logging und Monitoring einbauen

Gemeinsam mit Flows entsteht so eine leistungsfähige Integrationsplattform, die viele klassische Middleware-Szenarien direkt innerhalb von Directus abbilden kann.

Der nächste logische Schritt sind zeitgesteuerte Prozesse. Lesen Sie dazu unseren Leitfaden zu geplanten Flows mit Cron.

FAQ

Wie sichere ich einen eingehenden Webhook ab?

Am einfachsten über Secret-Header, Signatur-Prüfung und IP-Allow-Lists auf Reverse-Proxy-Ebene.

Kann ein Flow gleichzeitig einen Webhook senden und empfangen?

Ja. Ein Flow kann durch einen eingehenden Webhook gestartet werden und anschließend mehrere ausgehende Webhook-Requests ausführen.

Was ist der Unterschied zwischen Webhook-Trigger und Event Hook?

Ein Webhook-Trigger reagiert auf externe HTTP-Requests. Ein Event Hook reagiert auf Änderungen innerhalb von Directus.

Wie debugge ich fehlschlagende Webhooks?

Nutzen Sie Logging-Operations, prüfen Sie HTTP-Statuscodes und speichern Sie Fehlermeldungen in einer eigenen Collection.

Wann sollte ich Webhooks statt Event Hooks verwenden?

Immer dann, wenn externe Systeme beteiligt sind. Für rein interne Datenbankereignisse sind Event Hooks die bessere Wahl.