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.

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)
Workflow wird zur Ausführung eingereiht
Webhook antwortet sofort mit 202 Accepted
Workflow verarbeitet asynchron im Hintergrund

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 2 MB sein.

{
  "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

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

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

Auf Webhook-Daten zugreifen

Webhook-Daten sind getrennt in body (JSON-Payload) und query (URL-Parameter):

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}}

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
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.

Erste Schritte

Chat

Skills

Dateien

Agenten

Workflows

Integrationen

Microsoft Plugins

Modelle & Limits

Anleitungen

Account

Ressourcen

Fehlerbehebung

Webhook-Trigger

Überblick

Wann du den Webhook-Trigger verwenden solltest

Konfiguration

Basis-Einrichtung

Sicherheitsoptionen

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

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

​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

​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

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

Beispiel

Response-Codes

Nächste Schritte

FAQ