Externe Workflow-Aktion

Die Externe Workflow-Aktion sendet eine HTTP-Anfrage an eine beliebige externe URL, liest die JSON-Antwort aus und speichert ausgewählte Felder in Flow-Variablen, die Folgeaktionen nutzen können.

Typische Anwendungsfälle:

• Daten aus einem externen ERP oder CRM abfragen
• Lagerverfügbarkeit bei einem Lieferanten prüfen
• Einen n8n- oder Make-Workflow auslösen und dessen Ergebnis weiterverarbeiten
• Bestelldaten an ein externes Versandsystem übergeben und die Trackingnummer zurücklesen

---

Aktion einrichten

1. Öffnen Sie einen Flow im Editor und klicken Sie auf Aktion hinzufügen.
2. Wählen Sie den Typ Externer Workflow.
3. Füllen Sie die Felder aus:

Konfigurationsfelder

Feld	Pflicht	Beschreibung
URL	Ja	Ziel-URL der Anfrage. Template-Variablen wie {{trigger.orderId}} können in der URL verwendet werden.
Methode	Ja	POST, GET, PUT oder PATCH
Header	Nein	Schlüssel-Wert-Paare für HTTP-Header (z. B. Authorization: Bearer xyz). Unterstützt Template-Variablen.
Body	Nein	JSON-Body der Anfrage (nur für POST/PUT/PATCH). Unterstützt Template-Variablen.
Timeout (Sekunden)	Nein	Wie lange auf eine Antwort gewartet wird. Standard: 30, Maximum: 60.
Antwort-Mapping	Nein	Zeilen mit Variablenname und JSON-Pfad (→ Antwort-Mapping).
Ausgabe-Variable	Nein	Name der Variable, in der der vollständige Antwort-Body gespeichert wird (wenn kein Mapping definiert).

---

Antwort-Mapping

Das Antwort-Mapping ermöglicht es, gezielt einzelne Felder aus der JSON-Antwort in benannte Variablen zu extrahieren.

Jede Mapping-Zeile besteht aus:

• Variablenname — der Name, unter dem das Feld in {{var.name}} gespeichert wird
• JSON-Pfad — ein einfacher Pfadausdruck, der beschreibt, wo das Feld in der Antwort liegt

JSON-Pfad-Syntax

Beispiel-Antwort	JSON-Pfad	Ergebnis in {{var.x}}
{"status": "ok"}	$.status	ok
{"result": {"trackingId": "1Z..."}}	$.result.trackingId	1Z...
{"items": [{"id": 1}]}	$.items[0].id	1
(vollständiger Body)	(leer lassen)	Gesamter Antwort-JSON als Text

Lassen Sie das Pfad-Feld einer Zeile leer, um den vollständigen Antwort-Body in die Variable zu schreiben.

Beispiel: Tracking-Nummer abrufen

Angenommene Antwort des externen Systems:

{
  "shipment": {
    "trackingNumber": "1Z999AA10123456784",
    "carrier": "DHL",
    "estimatedDelivery": "2026-05-03"
  }
}

Mapping-Konfiguration:

Variablenname	JSON-Pfad
trackingNr	$.shipment.trackingNumber
carrier	$.shipment.carrier

In Folgeaktionen: {{var.trackingNr}} = 1Z999AA10123456784, {{var.carrier}} = DHL.

---

Template-Variablen in URL und Body

Sowohl die URL als auch der Body unterstützen {{trigger.x}}- und {{var.x}}-Variablen:

URL-Beispiel:

https://api.meinlager.de/bestellungen/{{trigger.orderId}}/versand

Body-Beispiel:

{
  "orderId": "{{trigger.orderId}}",
  "customerEmail": "{{trigger.customerEmail}}",
  "total": "{{trigger.total}}"
}

---

SSRF-Schutz

Anfragen an private oder interne Netzwerkadressen werden automatisch blockiert:

• Private IPv4-Bereiche: 10.x.x.x, 172.16–31.x.x, 192.168.x.x
• Loopback: 127.x.x.x, ::1
• Link-Local: 169.254.x.x
• Cloud-Metadaten-Endpunkte (z. B. 169.254.169.254)
• Nicht-HTTP(S)-Protokolle

Wenn Sie einen dieser Bereiche ansprechen möchten, schlägt die Aktion mit dem Fehler "URL not allowed (SSRF protection)" fehl. Dies ist ein Sicherheitsmerkmal und kann nicht deaktiviert werden.

---

Fehlerverhalten

HTTP-Statuscodes

Statuscode	Verhalten
2xx (200–299)	Erfolg — Antwort wird gemappt
4xx / 5xx	Aktion schlägt fehl
Timeout	Aktion schlägt fehl nach konfigurierten Sekunden

Bei einem Fehler gilt das am Aktions-Header konfigurierte Fehlerverhalten:

• Stopp (Standard): Flow-Ausführung wird abgebrochen.
• Fortfahren: Nächste Aktion wird trotzdem ausgeführt; Variablen bleiben leer.
• Wiederholen: Aktion wird bis zu 5-mal wiederholt (mit Backoff).

Häufige Fehlermeldungen

Fehlermeldung	Ursache	Lösung
URL not allowed (SSRF protection)	Ziel-URL ist eine private/interne Adresse	Externe, öffentliche URL verwenden
Request timed out	Endpunkt hat nicht innerhalb des Timeouts geantwortet	Timeout erhöhen (max. 60 s) oder Endpunkt prüfen
HTTP 401 Unauthorized	Fehlende oder falsche Authentifizierung	Authorization-Header mit korrektem Token prüfen
HTTP 422 Unprocessable Entity	Ungültiges JSON im Body	Body-Syntax und Content-Type-Header prüfen
Failed to parse JSON path	Antwort ist kein gültiges JSON	Antwort-Format des Endpunkts prüfen; Pfad anpassen

Debugging

1. Öffnen Sie die Ausführungshistorie und suchen Sie die fehlgeschlagene Ausführung.
2. Expandieren Sie das Log der "Externer Workflow"-Aktion — es zeigt den HTTP-Statuscode und den Antwort-Body (ersten 1 KB).
3. Prüfen Sie, ob der externe Endpunkt erreichbar ist und das erwartete JSON-Format zurückgibt.

---

Vollständiges Beispiel

Szenario: Bei einer neuen Bestellung die Lagerabfrage eines externen Systems aufrufen und die verfügbare Menge in einer Bedingung prüfen.

Flow-Aufbau:

1. Trigger: order.placed
2. Aktion 1 — Externer Workflow:
   • URL: https://lager.beispiel.de/api/stock/{{trigger.productId}}
   • Methode: GET
   • Header: Authorization: Bearer mein-api-schluessel
   • Mapping: verfuegbar → $.available_qty
3. Aktion 2 — Bedingte Verzweigung:
   • Ausdruck: {{var.verfuegbar}} < 2
   • Dann: Admin-Benachrichtigung "Lagerbestand kritisch"
   • Sonst: Keine weitere Aktion