n8n Webhook einrichten: Test und Produktions-URL

Einen kleinen Webhook anlegen

Unser eigenes Beispiel empfängt ein Lager-Testereignis. Es verschickt keine E-Mail und verändert keinen Warenbestand. Die sendende Anwendung soll eine Ereignis-ID, eine Artikelkennung und eine Menge liefern. So kannst du die Datenübertragung prüfen, bevor du einen fachlichen Folgeschritt anschließt.

1. Lege einen Workflow an und füge den Webhook-Node als Trigger hinzu.
2. Wähle POST als HTTP-Methode für dieses Beispiel.
3. Vergib einen eindeutigen Pfad, etwa lager-test. Prüfe, ob Methode und Pfad schon in einem anderen Workflow verwendet werden.
4. Wähle eine zu deinem Sender passende Authentifizierung und richte die erforderlichen Credentials ein.

Die Webhook-Referenz beschreibt Methode, Pfad und Antwortverhalten. Kopiere die URL aus deinem Node. Deine tatsächliche Instanz, ein möglicher Präfix und die Konfiguration bestimmen die vollständige Adresse. Wenn Menschen die Felder direkt eingeben sollen, zeigt n8n-Formulare mit dem Form Trigger einen getrennten Einstieg samt Test- und Produktionsweg.

Einen Testaufruf senden

Klicke im Node auf Listen for test event, bevor du die Testadresse aufrufst. Der Hersteller beschreibt dafür eine zeitlich begrenzte Registrierung. Die Test-URL allein hält den Listener nicht dauerhaft offen.

Speichere dieses eigene Beispieldokument als request.json:

{
  "event_id": "probe-001",
  "item_id": "ART-42",
  "quantity": 3
}

Ersetze im Aufruf DEINE_TEST_URL durch die gerade kopierte Testadresse. Ergänze die für deinen Node erforderliche Authentifizierung. Für Header Auth müssen Headername und geheimer Wert zum Credential passen:

curl -i -X POST "DEINE_TEST_URL" -H "Content-Type: application/json" -H "DEIN_HEADERNAME: DEIN_GEHEIMER_WERT" --data-binary "@request.json"

Die Platzhalter sind keine echten Zugangsdaten. Unter Windows PowerShell kannst du ausdrücklich curl.exe verwenden. Der Testaufruf gehört zu deiner eigenen n8n-Instanz; diese Anleitung behauptet keinen hier ausgeführten Lauf.

Eingangsdaten prüfen und Antwort festlegen

Prüfe im empfangenen Request zuerst die tatsächliche Struktur. Die Node-Dokumentation beschreibt die Bereiche body, headers, params und query. Für unseren JSON-Body liegt die Artikelkennung somit unter {{ $json.body.item_id }}. Ein Ausdruck für ein Feld auf der obersten Ebene würde eine andere Datenstruktur voraussetzen. Wie du solche Felder korrekt ansprichst, erklärt die Anleitung zu n8n Expressions. Enthält der Eingang mehrere Datensätze, prüfe mit dem Guide zu n8n-Schleifen zuerst, ob bereits einzelne Items oder noch eine Liste innerhalb eines Items vorliegen.

Für eine definierte JSON-Antwort wählst du im Webhook-Node bei Respond die Option Using 'Respond to Webhook' Node. Verbinde danach einen passenden Prüfschritt mit einem Respond to Webhook-Node. Dieser kann laut Antwortreferenz einen JSON-Body und einen HTTP-Status festlegen.

Lege vorher fest, was dein Status bedeuten soll: nur „Request angenommen“, „Pflichtfelder gültig“ oder „fachlicher Schritt abgeschlossen“. Eine sofort gesendete Bestätigung belegt noch nicht, dass spätere Nodes erfolgreich gelaufen sind. Eine eigene Antwort wie {"accepted": true} sollte deshalb genau zu dem vorher tatsächlich geprüften Schritt passen.

Teste außerdem einen fehlenden item_id-Wert und eine ungeeignete Menge. Lege selbst fest, welche Antworten diese Fälle erhalten sollen, und setze die entsprechende Prüfung im Workflow um. Der Webhook übernimmt deinen fachlichen Datenvertrag nicht automatisch.

Wenn ein weiterer Workflow selbst den Empfänger aufrufen soll, zeigt die Anleitung zum n8n HTTP Request die passende Senderseite.

Produktionsadresse gesondert prüfen

Der dokumentierte Entwicklungsablauf verlangt für Produktion einen gespeicherten und veröffentlichten Workflow. Ältere Oberflächen oder Anleitungen nennen dafür häufig „Active“. Richte dich nach deiner Version und prüfe den veröffentlichten Stand.

Die Umschaltung zwischen Test URL und Production URL im Node zeigt dir die jeweilige Adresse. Sie ersetzt die Veröffentlichung nicht. Kopiere danach bewusst die Produktionsadresse, sende einen eigenen Kontrollrequest und öffne die zugehörige Ausführung unter Executions.

Wenn deine Instanz hinter einem Proxy läuft, muss die angezeigte URL von deinem Sender aus erreichbar sein. Eine interne Containeradresse oder localhost ist für einen externen Dienst üblicherweise nicht dessen n8n-Server. Prüfe in diesem Fall die aktuelle Hostingkonfiguration deiner Instanz.

Zugriff und Wiederholungen planen

n8n dokumentiert Basic Auth, Header Auth und JWT Auth sowie eine IP(s) Allowlist im Webhook-Node. Wähle ein Verfahren, das deine sendende Anwendung unterstützt. Die Credential-Referenz beschreibt die nötigen Werte. Verwende für entfernte Aufrufe eine passende HTTPS-Verbindung.

Ein gemeinsames Secret gehört in die geschützte Konfiguration des Senders. Es lässt sich in öffentlich ausgeliefertem Browsercode nicht geheim halten. Wenn eine Website den Workflow auslösen soll, plane deshalb einen geeigneten geschützten Vermittlungsschritt oder eine zur Anwendung passende Anmeldung.

Unsere event_id ist eine eigene Entwurfsentscheidung für die Zuordnung von Wiederholungen. Wenn derselbe Request mehrfach ankommen kann, musst du ausdrücklich festlegen und implementieren, ob er erneut verarbeitet wird oder ob eine bereits bearbeitete ID erkannt werden soll. Das Feld allein erzeugt keinen eingebauten Wiederholungsschutz.

Die Anleitung zu n8n Credentials hilft dir, gespeicherte Zugangsdaten und ihre Zuordnung zu unterscheiden.

Häufige Fehler gezielt eingrenzen

Ändere für die Fehlersuche jeweils nur einen Punkt und sende einen kontrollierten Request. Notiere Methode, vollständige Zieladresse, Ereignis-ID, HTTP-Status und Ausführungsbefund. Damit kannst du unterscheiden, ob die Verbindung, die Registrierung oder die Verarbeitung angepasst werden muss.

Vier Testfälle vor dem produktiven Webhook

Ein erfolgreicher Beispielrequest ist erst der Anfang. Prüfe deinen Datenvertrag zusätzlich mit absichtlich ungeeigneten Eingaben. Unsere vier Fälle verwenden ausschließlich die fiktiven Lagerdaten aus diesem Artikel. Führe sie zunächst ohne produktive Folgeaktionen aus.

Für B und C brauchst du einen Prüfschritt vor dem Erfolgspfad, etwa eine passend konfigurierte Bedingung. Lege dessen Fehlerantwort ausdrücklich fest. Ein Webhook ohne diese Prüfung kann die Daten trotzdem annehmen. Ebenso verhindert event_id allein keine doppelte Verarbeitung.

Notiere zu jedem Fall den HTTP-Status, die Antwort und die zugehörige Ausführung. Wenn du sofort antwortest, vergleiche anschließend auch den späteren Ablauf: Die Empfangsbestätigung kann bereits gesendet sein, obwohl eine nachfolgende Node scheitert. Verwende für Produktion ein getrenntes Protokoll mit der tatsächlich kopierten Production URL.

Vier Testfälle als Textdatei herunterladen ↓