Webhook-Trigger

Überblick

Der Webhook-Trigger stellt einen HTTP-Endpoint bereit, den externe Systeme aufrufen können, um deinen Workflow zu starten. Er ist die Brücke zwischen Langdock Workflows und jedem externen Service oder jeder Anwendung, die HTTP-Anfragen senden kann.

Am besten für: Echtzeit-Integrationen, externe System-Events, API-gesteuerte Workflows und Verbindung von Services ohne native Integrationen.

Wann du den Webhook-Trigger verwenden solltest

Perfekt für:

Empfangen von Events von externen Services (GitHub, Stripe, eigene Apps)
Echtzeit-Datenverarbeitung von externen Systemen
Erstellen benutzerdefinierter Integrationen
Verbinden von Services, die Webhooks unterstützen (einschließlich anderer Workflows)
API-gesteuerte Workflows, die von anderen Systemen initiiert werden

Nicht ideal für:

Benutzerbezogene Datenerfassung (verwende Formular-Trigger)
Geplante wiederkehrende Aufgaben (verwende geplanten Trigger)
Native Integrations-Events (verwende Integrations-Trigger)

Konfiguration

Basis-Einrichtung

Wenn du einen Webhook-Trigger hinzufügst, erhältst du automatisch:

Eindeutige Webhook-URL: Ein sicherer Endpoint zum Empfangen von Anfragen
Webhook-ID: Kennung für deinen Webhook

Sicherheitsoptionen

Mit der Einstellung Authentifizierungsmethode legst du fest, wie dein Webhook gesichert wird. Wenn du eine Methode auswählst, wird automatisch ein Secret generiert. Das Secret bleibt erhalten, wenn du zwischen Methoden wechselst – so geht dein konfigurierter Schlüssel nicht versehentlich verloren.

Methode	Funktionsweise
Keine Authentifizierung	Der Webhook ist öffentlich zugänglich – jeder mit der URL kann ihn triggern. Geeignet für Tests und Anwendungsfälle mit geringem Sicherheitsbedarf.
Header	Das Secret wird über den HTTP-Header `X-Webhook-Secret` übermittelt. Die Webhook-URL bleibt dabei sauber; die UI zeigt einen curl-Beispielbefehl mit dem Header.
Query-Parameter	Das Secret wird als `?secret=...` an die URL angehängt. Dies ist das bisherige Verhalten und wird weiterhin vollständig unterstützt.

Wenn eine Authentifizierungsmethode ausgewählt ist, ist ein Secret erforderlich. Wird das Secret-Feld leer gelassen, erscheint eine Validierungswarnung. Best Practice: Verwende immer ein Secret für Produktions-Webhooks, um unbefugten Zugriff zu verhindern. Header-basierte Authentifizierung ist zu bevorzugen, da Secrets so nicht in Server-Logs oder dem Browser-Verlauf auftauchen.

Bestehende Webhooks mit einem Query-Parameter-Secret funktionieren weiterhin ohne Änderungen. Das Feld für die Authentifizierungsmethode ist optional – wenn es nicht gesetzt ist, bleibt das bisherige Verhalten automatisch erhalten.

Erweiterte Optionen

Aktiviere in Erweiterte Optionen die passende Option, wenn du Signatur-Header oder den originalen Request-Body im Workflow brauchst. Beide Optionen sind standardmäßig aus.

Signatur-Header einschließen: Fügt den Content-Type und unterstützte Signatur-Header unter headers zur Trigger-Ausgabe hinzu. Andere eingehende Header erscheinen nicht in der Ausgabe. Dazu gehören Signatur-Header von Stripe, GitHub, Slack, DocuSign, Shopify, Svix und Standard Webhooks.
Originalen Request-Body beibehalten: Behält den ungeparsten Original-Body unter rawBody in der Trigger-Ausgabe. Requests mit dieser Option sind auf 12 MB begrenzt, weil sowohl der geparste als auch der originale Body gespeichert werden.

Schalte beide ein, wenn ein späterer Step eine Provider-Signatur prüfen muss, etwa bei Stripe.

Wie es funktioniert

Externes System sendet HTTP POST-Anfrage an Webhook-URL
Webhook validiert Secret (falls konfiguriert, über X-Webhook-Secret-Header oder ?secret=-Query-Parameter)
Request-Payload wird geparst (JSON-Body und Query-Parameter). Das Parsing läuft auch, wenn Originalen Request-Body beibehalten eingeschaltet ist. Wenn Signatur-Header einschließen aktiv ist, stehen Content-Type und unterstützte Signatur-Header zusätzlich in der Trigger-Ausgabe bereit.
Workflow wird zur Ausführung eingereiht
Webhook antwortet sofort mit 202 Accepted
Workflow verarbeitet asynchron im Hintergrund

headers und rawBody erscheinen in der Trigger-Ausgabe nur, wenn der passende Schalter an diesem Webhook-Trigger eingeschaltet ist.

Webhooks verarbeiten immer asynchron. Der Webhook antwortet sofort mit 202 Accepted, während der Workflow im Hintergrund läuft.

Anfragen an deinen Webhook senden

Basis-Anfrage

# Ohne Authentifizierung
curl -X POST https://app.langdock.com/api/hooks/workflows/DEINE_WORKFLOW_ID \
  -H "Content-Type: application/json" \
  -d '{"key": "value"}'

# Header-Authentifizierung (empfohlen)
curl -X POST https://app.langdock.com/api/hooks/workflows/DEINE_WORKFLOW_ID \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Secret: DEIN_SECRET" \
  -d '{"key": "value"}'

# Query-Parameter-Authentifizierung (bisheriges Verhalten)
curl -X POST "https://app.langdock.com/api/hooks/workflows/DEINE_WORKFLOW_ID?secret=DEIN_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"key": "value"}'

Dateien senden

Sende Webhook-Dateien als JSON unter file für eine Datei oder unter files für bis zu 20 Dateien. Du kannst diese Keys auf oberster Ebene oder in verschachtelten Objekten verwenden. Jedes Dateiobjekt benötigt fileName, mimeType und ein Inhaltsfeld. Verwende base64 für Binärdateien wie XLSX-Dateien oder text für Textdateien. Der gesamte JSON-Request-Body muss einschließlich Base64-kodierter Inhalte kleiner als 25 MB sein. Wenn Originalen Request-Body beibehalten eingeschaltet ist, gilt ein Limit von 12 MB.

{
  "files": [
    {
      "fileName": "quarterly-report.xlsx",
      "mimeType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
      "base64": "UEsDB..."
    }
  ]
}

Beispiel-Anwendungsfälle

GitHub Webhook-Integration

Webhook-Trigger (GitHub Push-Events)
→ Agent: Analysiere Commit-Nachrichten
→ Condition: Prüfe, ob Dokumentation aktualisiert wurde
  → Ja: Regeneriere Docs
  → Nein: Fortfahren
→ Benachrichtigung: Sende Deployment-Status

GitHub Webhook-Konfiguration:

URL: Deine Webhook-URL
Events: Push, Pull Request
Content-Type: application/json

Aktiviere Signatur-Header einschließen im Langdock Webhook-Trigger, um x-hub-signature-256 zu erhalten.

Stripe-Zahlungs-Webhook

Webhook-Trigger (Stripe Events)
→ Code: Validiere Stripe-Signatur
→ Condition: Prüfe Event-Typ
  → payment_succeeded: Aktualisiere Benutzer-Account
  → payment_failed: Sende Retry-Benachrichtigung
  → subscription_canceled: Deaktiviere Zugriff

Aktiviere Signatur-Header einschließen und Originalen Request-Body beibehalten, damit der Code-Schritt stripe-signature aus trigger.output.headers und den originalen Body aus trigger.output.rawBody lesen kann.

Benutzerdefinierte Anwendungs-Integration

Webhook-Trigger
→ Code: Validiere und transformiere Daten
→ HTTP Request: Reichere Daten von externer API an
→ Agent: Analysiere und kategorisiere
→ Action: Erstelle Datensatz im CRM

Slack-Command-Integration

Webhook-Trigger (von Slack Slash-Command)
→ Agent: Verarbeite natürlichsprachlichen Befehl
→ HTTP Request: Führe Aktion in externem System aus
→ HTTP Response: Sende Ergebnis zurück zu Slack

Aktiviere Signatur-Header einschließen, um x-slack-signature und x-slack-request-timestamp zu erhalten.

Auf Webhook-Daten zugreifen

Webhook-Daten sind getrennt in body (JSON-Payload) und query (URL-Parameter). Wenn der passende Schalter unter Erweiterte Optionen eingeschaltet ist, enthält die Ausgabe zusätzlich headers und/oder rawBody.

Request-Body

Greife auf JSON-Payload-Felder zu:

{{trigger.output.body.user_id}}
{{trigger.output.body.event_type}}
{{trigger.output.body.data.amount}}

Dateien

Verarbeitete Dateien ersetzen die ursprünglichen Dateiobjekte im Request-Body. Greife auf Dateien unter files in trigger.output.body.files zu:

{{trigger.output.body.files[0].path}}
{{trigger.output.body.files[0]._metadata.name}}
{{trigger.output.body.files[0]._metadata.mimeType}}

Verwende für eine Datei unter file den Pfad {{trigger.output.body.file.path}}.

Query-Parameter

Greife auf URL-Query-Parameter zu:

{{trigger.output.query.param_name}}

Wenn Signatur-Header einschließen aktiv ist, greife auf den Content-Type und unterstützte Signatur-Header zu:

{{trigger.output.headers["content-type"]}}
{{trigger.output.headers["stripe-signature"]}}

Die Header-Namen in der Ausgabe sind kleingeschrieben, zum Beispiel content-type und stripe-signature. Nicht unterstützte Namen erscheinen nicht.

Raw Body

Wenn Originalen Request-Body beibehalten eingeschaltet ist, greife auf den ungeparsten Original-Body als String zu. GET-Anfragen setzen rawBody auf einen leeren String.

{{trigger.output.rawBody}}

Beispiel

Für eine Anfrage wie:

POST /api/hooks/workflows/abc123?source=github
Body: {"event": "push", "repo": "my-repo"}

Greife auf die Daten zu:

Source: {{trigger.output.query.source}}
Event: {{trigger.output.body.event}}
Repo: {{trigger.output.body.repo}}

Response-Codes

Code	Bedeutung	Wann es passiert
202	Accepted	Workflow erfolgreich eingereiht
400	Bad Request	Ungültige Workflow-ID, Format oder Secret
404	Not Found	Workflow nicht gefunden
413	Payload Too Large	Original-Body über 12 MB, oder kombinierte Ausgabe über 25 MB
429	Too Many Requests	Rate-Limit oder Ausgabenlimit erreicht
500	Server Error	Interner Fehler bei Webhook-Verarbeitung

Nächste Schritte

Integrations-Trigger

Verwende native Integrations-Events

HTTP-Request-Node

Stelle Anfragen an externe APIs

Code-Node

Validiere und transformiere Webhook-Daten

Erste Schritte

Erstelle deinen ersten Workflow

FAQ

Wie löse ich einen Workflow aus einem externen Dienst aus?

Nutze einen Webhook-Trigger, wenn ein externer Dienst einen Workflow über eine HTTP-Anfrage starten soll. Konfiguriere den externen Dienst so, dass er die Webhook-URL des Workflows mit der erwarteten Methode, den Headern und dem Payload aufruft.

Was sollte ich prüfen, wenn ein Webhook-Trigger nicht auslöst?

Prüfe die Webhook-URL, die Request-Methode, Anforderungen an Authentifizierung oder Signierung, die Struktur des Payloads und ob der externe Dienst die Anfrage tatsächlich gesendet hat. Stelle außerdem sicher, dass der Workflow aktiv ist und alle Pflichtfelder im eingehenden Payload vorhanden sind.

​Überblick

​Wann du den Webhook-Trigger verwenden solltest

​Konfiguration

​Basis-Einrichtung

​Sicherheitsoptionen

​Erweiterte Optionen

​Wie es funktioniert

​Anfragen an deinen Webhook senden

​Basis-Anfrage

​Dateien senden

​Beispiel-Anwendungsfälle

​GitHub Webhook-Integration

​Stripe-Zahlungs-Webhook

​Benutzerdefinierte Anwendungs-Integration

​Slack-Command-Integration

​Auf Webhook-Daten zugreifen

​Request-Body

​Dateien

​Query-Parameter

​Header

​Raw Body

​Beispiel

​Response-Codes

​Nächste Schritte

Integrations-Trigger

HTTP-Request-Node

Code-Node

Erste Schritte

​FAQ

Überblick

Wann du den Webhook-Trigger verwenden solltest

Konfiguration

Basis-Einrichtung

Sicherheitsoptionen

Erweiterte Optionen

Wie es funktioniert

Anfragen an deinen Webhook senden

Basis-Anfrage

Dateien senden

Beispiel-Anwendungsfälle

GitHub Webhook-Integration

Stripe-Zahlungs-Webhook

Benutzerdefinierte Anwendungs-Integration

Slack-Command-Integration

Auf Webhook-Daten zugreifen

Request-Body

Dateien

Query-Parameter

Header

Raw Body

Beispiel

Response-Codes

Nächste Schritte

FAQ