Webhook

Verwenden Sie den Webhook-Trigger, wenn ein Flow als Reaktion auf einen HTTP-Aufruf von außerhalb von Business Central starten soll – ein Drittanbieter-Callback, eine eigene Integration, ein Slack-Bot, alles, was eine URL aufrufen kann. Der Flow kann vollständig asynchron laufen (der Aufrufer erhält sofort eine Antwort) oder synchron bis zu einem Schritt „Auf Webhook antworten" (der Aufrufer wartet auf die Antwort des Flows).

Typische Beispiele:

• Empfangen eines Callbacks vom Zahlungs-Provider und Aktualisieren der zugehörigen Rechnung.
• Ein Partner-Portal soll einen Auftragsimport auslösen.
• Als Brücke fungieren, die ein eingehendes Payload transformiert und an ein anderes System weiterreicht.

Erfordert AutoFlow Premium

Der Webhook-Trigger ist eine Premium-Funktion. Die Umgebung, in der Sie den Flow veröffentlichen, benötigt eine aktive AutoFlow-Lizenz ab Premium (Premium, Ultimate oder Unlimited). Mit Starter und dem kostenlosen Tarif lässt sich ein Webhook-Flow zwar erstellen, er wird aber erst aktiv, wenn das Paket hochgestuft wird. Siehe Lizenzierung weiter unten.

Nur in Business Central Online

Der Webhook-Trigger erreicht deine Umgebung über den AutoFlow-Webhook-Proxy und funktioniert deshalb nur in Business Central Online (SaaS). In einer On-Premises-Installation lässt sich der Trigger nicht konfigurieren – beim Öffnen der Konfiguration erscheint „Der Webhook-Trigger ist nur in Business Central online (SaaS) verfügbar. On-Premises kann er nicht konfiguriert werden." und es wird kein Endpunkt registriert. Um einen Flow von außen in einem On-Premises-Business-Central zu starten, nimm einen geplanten Flow, der abfragt, oder rufe den Flow über einen eigenen Business-Central-Webservice auf.

Lizenzierung

Eingehende Webhooks sind ab dem Paket AutoFlow Premium verfügbar. Geprüft wird die der Umgebung zugewiesene Lizenz, nicht der einzelne Benutzer – unabhängig davon, wer den Flow veröffentlicht, muss die Zielumgebung mindestens Premium halten.

Sandboxes sind ausgenommen. In einer Sandbox-Umgebung können Sie einen Webhook-Flow mit jedem Paket erstellen, veröffentlichen und testen – so lässt er sich ausprobieren, bevor er produktiv geht. Die Premium-Anforderung gilt nur, wenn der Flow in einer Produktivumgebung veröffentlicht wird.

Was Sie sehen, wenn die Umgebung nicht dafür lizenziert ist: Das Veröffentlichen des Flows ist weiterhin erfolgreich (nichts geht verloren), aber der Registrierungsstatus auf der Flow-Karte zeigt „Der Webhook-Trigger erfordert mindestens AutoFlow Premium." und der Endpunkt wird nicht registriert – Aufrufe erreichen den Flow nicht.

So aktivieren Sie ihn: Stufen Sie das Paket der Umgebung im AutoFlow-Portal auf Premium (oder höher) hoch und veröffentlichen Sie den Webhook-Flow erneut. Beim nächsten Veröffentlichen wird der Endpunkt registriert und der Status wechselt zu Registriert – der Webhook ist aktiv.

Ein bereits aktiver Webhook läuft für die restliche Laufzeit der Lizenz weiter; die Prüfung greift beim Veröffentlichen eines Webhooks oder beim Neu-Erzeugen seiner URL. Damit eine Integration aktiv bleibt, halten Sie die Umgebung auf Premium oder höher.

So funktioniert es

1. Sie veröffentlichen einen Webhook-Flow. AutoFlow registriert ihn und vergibt eine eindeutige Endpunkt-URL auf dem AutoFlow-Webhook-Proxy – sie wird auf der Flow-Karte angezeigt.
2. Ein Aufrufer sendet eine HTTP-Anfrage an diese URL, mit beliebigem Payload (oder ohne). Vom Aufrufer werden keine Business-Central-Anmeldung, kein API-Schlüssel und kein Secret benötigt.
3. Der AutoFlow-Proxy leitet die Anfrage in Ihr Business Central weiter und startet den Flow. Methode, Header, Query-String und Body der Anfrage werden dem Flow als Trigger-Ausgaben übergeben.
4. Der Aufrufer erhält die echte HTTP-Antwort Ihres Flows – den Statuscode und den Body, den der Flow zurückgibt, ohne jede Umhüllung. Gibt der Flow nichts Eigenes zurück, erhält der Aufrufer die Standardantwort des Triggers.

Die URL ist die Berechtigung – wer sie hat, kann den Flow auslösen. Behandeln Sie sie wie ein Passwort: nur über HTTPS senden, im Secret-Store Ihres Aufrufers ablegen und neu erzeugen, falls sie nach außen gelangt.

Die Endpunkt-URL

Nachdem Sie den Flow veröffentlicht haben, zeigt der Abschnitt Webhook-Aufruf auf der Flow-Karte die Endpunkt-URL. Sie sieht so aus:

https://webhook.autoflow365.app/<org>/<id>

• Wo Sie sie finden: Öffnen Sie den Flow, sehen Sie im Abschnitt Webhook-Aufruf nach und kopieren Sie die Endpunkt-URL in Ihren Aufrufer. Sie erscheint, sobald der Flow veröffentlicht ist.
• Sie ist eindeutig für diesen Flow und diese Umgebung. Ein Flow, der in eine andere Umgebung kopiert (oder dupliziert) wird, erhält beim Veröffentlichen seine eigene neue URL – die alte wird nie übernommen.
• Neu erzeugen: Die Aktion Webhook-URL neu erzeugen vergibt eine neue URL und deaktiviert die alte sofort. Verwenden Sie sie, wenn die URL nach außen gelangt ist oder Sie sie rotieren möchten.

Zulässige HTTP-Methoden

In der Trigger-Konfiguration wählen Sie, welche HTTP-Methoden dieser Webhook akzeptiert – GET, POST, PUT, PATCH, DELETE. Eine Anfrage mit einer anderen Methode wird vom Proxy mit 404 abgewiesen, genau so, als gäbe es die URL nicht, und erreicht Business Central gar nicht.

Aktivieren Sie nur die Methoden, die Ihr Aufrufer tatsächlich verwendet. Eine eng gehaltene Liste verkleinert die Angriffsfläche des Endpunkts und lässt versehentliche Aufrufe sauber fehlschlagen.

Was der Flow erhält

Der Trigger stellt die eingehende Anfrage dem restlichen Flow als vier Ausgaben zur Verfügung:

Ausgabe	Beschreibung
Payload	Der rohe Anfrage-Body, genau so, wie der Aufrufer ihn gesendet hat (meist ein JSON-String). Mit den JSON-Schritten parsen oder mit SmartFields auslesen.
Method	Die HTTP-Methode des Aufrufs (GET, POST, …).
Headers	Die Anfrage-Header als JSON-Objekt (ein String), z. B. um einen eigenen X-…-Header zu lesen.
Query	Der rohe Query-String aus der URL (alles nach dem ?), falls vorhanden.

Dem Aufrufer antworten

Ob der Aufrufer auf Ihren Flow wartet – und was er zurückbekommt – hängt vom Antwort-Modus des Triggers ab.

• Sofortige Rückgabe (Standard): Der Aufrufer erhält sofort die Standardantwort, und der Flow läuft im Hintergrund. Für „Feuern und Vergessen"-Integrationen.
• Auf Antwort-Schritt warten: Der Trigger hält die HTTP-Anfrage des Aufrufers offen, bis der Flow einen Schritt Auf Webhook antworten erreicht (oder das Synchron-Timeout greift). Wenn der Aufrufer eine synchrone Rückmeldung des Flows benötigt.

vorsicht

Sleep und andere zeitbasierte Verzögerungsschritte müssen nach dem Schritt „Auf Webhook antworten" stehen. Das synchrone Antwortfenster kann nicht pausiert werden – eine Verzögerung davor führt beim Aufrufer zu einem Fehler.

Der Schritt „Auf Webhook antworten"

Im Modus Auf Antwort-Schritt warten ist der Schritt Auf Webhook antworten (aus der Palette „Essentials") das, was den Aufrufer freigibt. Fügen Sie ihn dort ein, wo der Aufrufer seine Antwort erhalten soll – in der Regel so früh wie möglich, mit der aufwändigen Arbeit dahinter. Wenn er ausgeführt wird:

1. Der Runner wertet den konfigurierten Statuscode, Content-Type und Body aus (mit aufgelösten SmartFields und SmartFormulas).
2. Diese werden zur echten HTTP-Antwort des Aufrufers.
3. Der Runner verlässt das synchrone Fenster. Alle Schritte nach „Auf Webhook antworten" laufen asynchron weiter – aus Sicht des Aufrufers ist die Anfrage bereits beendet.

Beendet der Flow (oder erreicht das Synchron-Timeout), ohne je einen Schritt „Auf Webhook antworten" zu erreichen, erhält der Aufrufer den Standard-Antwort-Statuscode und den Content-Type des Triggers mit leerem Body.

Im Modus Sofortige Rückgabe ist der Schritt wirkungslos: Der Aufrufer hat die Standardantwort bereits erhalten, bevor der Flow gestartet ist, daher wird jeder Schritt „Auf Webhook antworten" ignoriert.

Typische Muster:

• Zuerst bestätigen, später arbeiten: Sofort {"received": true} zurückgeben und dann die langsame nachgelagerte Arbeit asynchron erledigen.
• Synchrone Validierung: Eine schnelle Prüfung ausführen und ein Ergebnis zurückgeben (z. B. 422 mit {"approved": false, "reason": "..."}) an ein Partner-Portal.
• API-Brücke: Ein transformiertes Payload an ein anderes System weiterreichen und dessen Antwort als Webhook-Antwort zurückgeben.

Den Schritt „Auf Webhook antworten" konfigurieren

• Statuscode – der an den Aufrufer zurückgegebene HTTP-Status. Bereich 200..599 (1xx-Codes werden abgelehnt). 200/201 für Erfolg, 4xx für Aufrufer-Fehler (422 für Validierung), 5xx für Backend-Probleme.
• Content-Type – der MIME-Typ des Bodys. application/json ist am gebräuchlichsten; text/plain für Diagnosetexte, application/xml für SOAP-artige Antworten.
• Body – der Antwort-Body. Unterstützt SmartFields und SmartFormulas, sodass Sie ihn aus den Ausgaben vorheriger Schritte zusammensetzen können.

Registrierung und Status

Beim Veröffentlichen eines Webhook-Flows wird dieser beim AutoFlow-Portal registriert und die Verbindung in Ihr Business Central bereitgestellt. Der Abschnitt Webhook-Aufruf auf der Flow-Karte spiegelt den Zustand im Feld Registrierungsstatus wider – klicken Sie darauf, um den nächsten Schritt auszuführen, wenn einer nötig ist:

Status	Bedeutung
Registriert – der Webhook ist aktiv.	Der Endpunkt ist registriert und Aufrufe erreichen den Flow. Nichts zu tun.
Registrierung ausstehend – zum Wiederholen klicken.	Das Portal war beim Veröffentlichen nicht erreichbar. Zum Wiederholen klicken oder einfach erneut veröffentlichen.
Administratorzustimmung erforderlich – zum Erteilen klicken.	Ein Business-Central-Administrator muss die Zustimmung erteilen, damit AutoFlow Aufrufe in diesen Mandanten empfangen darf (ein einmaliger Schritt pro Mandant). Klicken, um zu prüfen und die Zustimmungsseite zu öffnen.
Erfordert mindestens AutoFlow Premium.	Die Produktivumgebung ist nicht für Webhooks lizenziert. Siehe Lizenzierung.

Berechtigungen – der Webhook-Benutzer

Ein eingehender Webhook hat keinen angemeldeten Benutzer, daher läuft der Flow als eigener Webhook-Anwendungsbenutzer. AutoFlow erteilt diesem Benutzer die Berechtigungen, die die Flow-Engine benötigt, automatisch. Wenn ein Schritt in Ihrem Flow andere Daten liest oder schreibt – eigene Tabellen oder Daten einer anderen Erweiterung –, müssen Sie diesem Benutzer den entsprechenden Zugriff selbst erteilen.

Verwenden Sie den Link „Dem Webhook-Benutzer die erforderlichen Berechtigungen zuweisen" auf der Flow-Karte, um diesen Benutzer zu öffnen und die benötigten Berechtigungssätze hinzuzufügen. Schlägt ein Schritt wegen einer fehlenden Berechtigung fehl, wird dies im Ausführungsprotokoll des Flows festgehalten, sodass Sie genau sehen, was zu erteilen ist.

Den Trigger konfigurieren

Öffnen Sie den Flow-Editor, wählen Sie Wenn ein Webhook empfangen wird und füllen Sie die Konfigurationskarte aus.

• Beschreibung – geben Sie an, was diesen Flow auslöst. Erscheint in Trigger-Listen und im Ausführungsverlauf.
• Zulässige HTTP-Methoden – die Methoden, die dieser Webhook akzeptiert (siehe Zulässige HTTP-Methoden). Mindestens eine aktivieren.
• Antwort-Modus – Sofortige Rückgabe oder Auf Antwort-Schritt warten (siehe Dem Aufrufer antworten).
• Synchron-Timeout (Sekunden) – wie lange die synchrone Phase eines Aufrufs im Modus Auf Antwort-Schritt warten laufen darf, bevor der Aufrufer die Standardantwort erhält und der Flow im Hintergrund weiterläuft. Standard 30 Sekunden; nur im Modus Auf Antwort-Schritt warten sichtbar.
• Standard-Antwort-Statuscode / Content-Type – was der Aufrufer sieht, wenn der Flow endet, ohne einen Schritt „Auf Webhook antworten" zu erreichen (Timeouts, gar kein Respond, oder Modus Sofortige Rückgabe). Standards: 200 und application/json.

Beispielaufruf

curl -X POST \
  "https://webhook.autoflow365.app/<org>/<id>" \
  -H 'Content-Type: application/json' \
  -d '{ "customerNo": "C-001", "name": "Acme" }'

Die Antwort ist die echte HTTP-Antwort des Flows. Mit einem Schritt „Auf Webhook antworten", der 201 und einen JSON-Body zurückgibt, sieht der Aufrufer genau das:

HTTP/1.1 201 Created
Content-Type: application/json

{"ok":true}

Keine Umhüllung, kein Wrapper – Statuszeile und Body sind die des Flows selbst.

Fehler, die der Aufrufer sehen kann

Diese kommen vom Proxy, vor oder um Ihren Flow herum:

• 404 – die URL ist unbekannt, wurde neu erzeugt oder entfernt, oder die Anfrage hat eine Methode verwendet, die nicht in der Liste der zulässigen Methoden steht. (Alle vier Fälle sehen bewusst identisch aus – eine unbekannte URL verrät nichts.)
• 502 – der Flow hat einen Fehler ausgelöst, oder Business Central war nicht erreichbar.
• 504 – die synchrone Phase lief über das Synchron-Timeout hinaus und Business Central hat nicht rechtzeitig geantwortet.

Jeder andere Status (200, 201, 422, …) ist die eigene Antwort Ihres Flows.

Bewährte Vorgehensweisen

• Behandeln Sie die URL als Secret. Sie ist die Berechtigung – nur über HTTPS verwenden, im Secret-Store Ihres Aufrufers ablegen und neu erzeugen, falls sie nach außen gelangt.
• Halten Sie die Methoden eng. Aktivieren Sie nur die HTTP-Methoden, die Ihr Aufrufer verwendet; alles andere gibt 404 zurück.
• Antworten Sie schnell. Platzieren Sie „Auf Webhook antworten" im Modus Auf Antwort-Schritt warten früh, damit der Aufrufer nicht durch langsame nachgelagerte Arbeit blockiert wird; lang laufende Schritte kommen danach.
• Wählen Sie bewusste Antwort-Statuscodes. Verwenden Sie 200 nicht für Fehlerfälle – 4xx/5xx machen die Fehlerbehandlung auf Aufrufer-Seite handhabbar.
• Geben Sie dem Webhook-Benutzer, was er braucht. Berührt ein Schritt Daten außerhalb der Flow-Engine, weisen Sie diesen Zugriff dem Webhook-Benutzer zu; eine fehlende Berechtigung erscheint im Ausführungsprotokoll.
• Halten Sie die Umgebung lizenziert. Ein produktiver Webhook benötigt AutoFlow Premium oder höher; eine Herabstufung stoppt neue Registrierungen.