HTTP-Request (flow.http-request)
Ruft einen externen Server per HTTP auf; die Antwort kann gespeichert werden.
Mit diesem Baustein kann Ihr Flow eine Verbindung zu externen Diensten herstellen — zum Beispiel um Daten von einer Schnittstelle abzurufen, eine Benachrichtigung an ein anderes System zu senden oder einen Genehmigungsstatus in einer externen Datenbank zu aktualisieren. Der Baustein ist blau gekennzeichnet und gehört zur Kategorie der Aktions-Bausteine.
Wofür Sie diesen Baustein nutzen
Immer dann, wenn Ihr Flow mit einer anderen Software oder einem Web-Dienst sprechen soll, ist der HTTP-Request-Baustein die richtige Wahl. Typische Anwendungsfälle an Schulen:
- Abrufen von Daten: Ein externer Kalender-Dienst oder ein Vertretungsplan-System stellt Informationen über eine Schnittstelle bereit, die Sie in Ihren Flow einbinden möchten.
- Senden von Benachrichtigungen: Sie möchten beim Abschluss eines Genehmigungsschritts automatisch eine Nachricht an einen Webhook — zum Beispiel in einem Chat-System oder einem Ticket-System — versenden.
- Aktualisieren externer Datensätze: Ein Antragsformular in Prilog soll nach Genehmigung direkt einen Datensatz in einer Drittsoftware anlegen oder verändern.
INFO
Dieser Baustein setzt voraus, dass der externe Dienst über eine öffentlich erreichbare HTTPS-Adresse verfügt. Verbindungen zu internen Netzwerkadressen sind aus Sicherheitsgründen nicht möglich (siehe unten).
Die Einstellungen im Detail
| Feld | Pflicht | Was es bewirkt |
|---|---|---|
| Methode | nein | Legt fest, welche Art von HTTP-Anfrage gesendet wird (Standard: GET) |
| URL | ja | Die vollständige Adresse des externen Servers |
| Headers (JSON) | nein | Zusätzliche Kopfzeilen, die mit der Anfrage mitgeschickt werden |
| Body (JSON) | nein | Der Inhalt, der an den Server übermittelt wird (nur bei POST, PUT, PATCH, DELETE) |
| Secret-Ref (Bearer) | nein | Verweis auf ein gespeichertes Zugangs-Token für gesicherte Schnittstellen |
| Timeout (ms) | nein | Wie lange der Flow auf eine Antwort wartet, bevor er abbricht |
| Antwort speichern als | nein | Name der Variable, unter der die Antwort des Servers gespeichert wird |
Methode
Hier wählen Sie aus, welche Aktion gegenüber dem externen Server ausgeführt werden soll. Zur Verfügung stehen:
- GET — Daten abrufen, ohne etwas zu verändern. Dies ist die häufigste Wahl, wenn Sie nur Informationen lesen möchten, zum Beispiel den aktuellen Status eines Datensatzes.
- POST — Neue Daten an den Server senden, zum Beispiel einen neuen Eintrag anlegen.
- PUT — Einen bestehenden Datensatz vollständig ersetzen.
- PATCH — Einen bestehenden Datensatz teilweise aktualisieren, also nur einzelne Felder ändern.
- DELETE — Einen Datensatz auf dem externen Server löschen.
Beispiel: Wenn Ihr Schulverwaltungs-System eine Schnittstelle anbietet, über die Sie eine Abwesenheit melden können, verwenden Sie in der Regel POST (neue Meldung anlegen) oder PATCH (bestehende Meldung ergänzen).
URL
Die vollständige Webadresse des externen Dienstes, den Sie ansprechen möchten. Die Adresse muss mit http:// oder https:// beginnen; jedes andere Format wird abgelehnt.
In der URL können Variablen aus dem Flow verwendet werden, zum Beispiel:
https://api.mein-dienst.de/schueler/${data.schuelerId}/abwesenheitPrilog setzt den Wert von schuelerId dann automatisch ein, bevor die Anfrage gesendet wird.
WARNING
Aus Sicherheitsgründen sind bestimmte Zieladressen dauerhaft gesperrt. Der Baustein verweigert Verbindungen zu:
localhostund127.x.x.x- Interne Netzwerke:
10.x.x.x,192.168.x.x,172.16.x.xbis172.31.x.x - Verbindungs-lokale Adressen:
169.254.x.x - Cloud-Metadaten-Adressen (zum Schutz der Server-Infrastruktur)
Diese Einschränkung schützt Ihre Prilog-Instanz und die dahinterliegenden Server vor unbeabsichtigtem oder missbräuchlichem Zugriff auf interne Dienste.
Headers (JSON)
Manche externen Dienste erwarten zusätzliche Informationen im HTTP-Header — zum Beispiel eine API-Version oder einen speziellen Identifikator. Tragen Sie diese als JSON-Objekt ein:
{"X-API-Key": "meinschluessel", "Accept-Language": "de"}Dieses Feld ist optional. Wenn Sie unsicher sind, ob Ihr Dienst spezielle Header benötigt, schauen Sie in die Dokumentation des jeweiligen Anbieters.
TIP
Wenn Sie eine Authentifizierung per Bearer-Token benötigen, verwenden Sie besser das Feld „Secret-Ref (Bearer)" weiter unten — so bleibt das Token sicher in den Tenant-Einstellungen gespeichert und taucht nicht im Flow-Text auf.
Body (JSON)
Der Inhalt, den Sie an den externen Server übermitteln möchten. Tragen Sie hier ein JSON-Objekt ein, zum Beispiel:
{"antragId": "${data.antragId}", "status": "genehmigt", "genehmigtVon": "${data.userName}"}Wichtig: Der Body wird nur bei den Methoden POST, PUT, PATCH und DELETE berücksichtigt. Bei GET wird dieses Feld ignoriert, da GET-Anfragen per Konvention keinen Inhalt übertragen.
Wenn der Body ein gültiges JSON-Objekt enthält, setzt Prilog den Header Content-Type: application/json automatisch — Sie müssen das nicht selbst eintragen.
Secret-Ref (Bearer)
Viele externe Schnittstellen verlangen ein Zugangs-Token, um sicherzustellen, dass nur berechtigte Systeme auf sie zugreifen dürfen. Tragen Sie hier den Namen des Tokens ein, wie es in den Tenant-Secrets Ihrer Prilog-Instanz hinterlegt ist — nicht das Token selbst.
Prilog sucht das Token dann zur Laufzeit aus dem Secrets-Speicher und fügt es als Authorization: Bearer …-Header der Anfrage bei. Das eigentliche Token ist damit zu keinem Zeitpunkt im Flow sichtbar oder gespeichert, was das Risiko eines versehentlichen Datenlecks deutlich reduziert.
Beispiel: Wenn das Token in den Tenant-Secrets unter dem Namen mein-dienst-api-token hinterlegt ist, tragen Sie hier mein-dienst-api-token ein.
Timeout (ms)
Legt fest, wie viele Millisekunden der Flow auf eine Antwort des externen Servers wartet, bevor er die Anfrage als fehlgeschlagen wertet. Der Standardwert beträgt 10000 (entspricht 10 Sekunden). Der Mindestwert ist 100 ms, der Höchstwert 60000 ms (= 60 Sekunden).
Der Wert kann in Schritten von 100 angepasst werden. Wenn Ihr Dienst erfahrungsgemäß etwas länger braucht — zum Beispiel weil er im Hintergrund Berechnungen anstellt —, können Sie den Timeout entsprechend erhöhen. Wählen Sie ihn jedoch nicht unnötig hoch, da ein hängender Flow alle Beteiligten aufhält.
Antwort speichern als
Wenn der externe Dienst Daten zurückschickt, die Sie in einem späteren Schritt des Flows verwenden möchten, tragen Sie hier einen Variablennamen ein. Die Antwort des Servers wird dann unter diesem Namen gespeichert und ist in allen nachfolgenden Bausteinen als ${data.<name>} verfügbar.
Beispiel: Sie tragen genehmigungsAntwort ein. Dann können Sie in einem späteren Textbaustein schreiben:
Der externe Dienst hat geantwortet: ${data.genehmigungsAntwort.status}Variablen / Platzhalter
Sie können in den Feldern URL, Headers und Body auf Variablen aus dem laufenden Flow zugreifen. Die Schreibweise ist einheitlich:
${data.feldname}Wenn ein früherer Baustein zum Beispiel die Variable schuelerId gesetzt hat, können Sie diese überall in den Einstellungen des HTTP-Request-Bausteins verwenden:
- In der URL:
https://api.dienst.de/schueler/${data.schuelerId} - Im Body:
{"id": "${data.schuelerId}", "aktion": "abmelden"} - In einem Header:
{"X-Schueler": "${data.schuelerId}"}
Wenn Sie im Feld Antwort speichern als einen Namen eingetragen haben — zum Beispiel serverAntwort —, erzeugt der Baustein nach erfolgreichem Abschluss eine neue Variable ${data.serverAntwort}. Diese enthält das vollständige Antwortobjekt des Servers (siehe nächster Abschnitt) und kann von allen nachfolgenden Bausteinen gelesen werden.
Was dabei herauskommt
Nach dem Ausführen des Bausteins stehen folgende Werte zur Verfügung, sofern Sie unter „Antwort speichern als" einen Variablennamen vergeben haben:
| Feld | Typ | Bedeutung |
|---|---|---|
statusCode | Zahl | Der HTTP-Statuscode der Antwort (z. B. 200, 201, 404, 500) |
ok | Ja/Nein | true, wenn der Statuscode im Bereich 200–299 liegt; sonst false |
body | Objekt oder Text | Der eigentliche Inhalt der Antwort |
Antwortet der externe Server mit einem gültigen JSON-Dokument, wird der body automatisch in ein strukturiertes Datenobjekt umgewandelt. Sie können dann auf einzelne Felder zugreifen, zum Beispiel ${data.serverAntwort.body.status}.
INFO
Antworten mit mehr als 1 MB Größe werden abgewiesen. Prilog speichert in diesem Fall keinen Body und markiert den Schritt als fehlgeschlagen.
Der Baustein gilt als erledigt, wenn der Statuscode im 2xx-Bereich liegt (also ok den Wert true hat). Bei allen anderen Statuscodes — zum Beispiel 404 (nicht gefunden) oder 500 (Server-Fehler) — wird der Schritt als fehlgeschlagen markiert.
Wenn etwas schiefgeht
Der Baustein meldet in folgenden Situationen einen Fehler:
- URL leer: Das Pflichtfeld URL wurde nicht ausgefüllt.
- Ungültige URL: Die eingetragene Adresse ist kein gültiges URL-Format.
- Nur http/https erlaubt: Die URL beginnt mit einem anderen Protokoll (z. B.
ftp://). - Host blockiert: Die Zieladresse liegt in einem privaten oder internen Adressbereich (siehe Abschnitt „URL" oben).
- Antwort zu groß: Der Server hat mehr als 1 MB zurückgesendet.
- Aufruf fehlgeschlagen: Es konnte keine Verbindung zum Server hergestellt werden — zum Beispiel weil der Dienst gerade nicht erreichbar ist oder ein DNS-Fehler vorliegt.
- Timeout überschritten: Der Server hat nicht innerhalb der eingestellten Zeit geantwortet.
TIP
Wenn ein Flow regelmäßig wegen Timeout abbricht, prüfen Sie zunächst, ob der externe Dienst aktuell verfügbar ist. Ist er grundsätzlich langsam, können Sie den Timeout-Wert vorsichtig erhöhen — bedenken Sie aber, dass der Flow so lange auf eine Antwort wartet und in dieser Zeit keine weiteren Schritte ausführt.
Beispiel
Szenario: Nach Genehmigung eines Dienstreiseantrags soll automatisch ein Eintrag in einem externen Buchungssystem angelegt werden.
Einstellungen des Bausteins:
- Methode: POST
- URL:
https://buchung.schule-musterstadt.de/api/reisen - Headers:
{"X-Tenant": "schule-musterstadt"} - Body:json
{ "antragstellerId": "${data.antragStellerId}", "reiseziel": "${data.reiseziel}", "datum": "${data.reiseDatum}", "genehmigt": true } - Secret-Ref (Bearer):
buchungssystem-api-token - Timeout (ms):
15000 - Antwort speichern als:
buchungsBestaetigung
Nach dem Ausführen des Bausteins enthält ${data.buchungsBestaetigung.statusCode} den HTTP-Statuscode des Buchungssystems, und ${data.buchungsBestaetigung.ok} gibt an, ob die Buchung erfolgreich angelegt wurde. Ein nachfolgender Benachrichtigungs-Baustein kann diese Werte verwenden, um dem Antragsteller eine Rückmeldung zu schicken.