HTTP Webhook-Authentifizierung

Verbinden Sie UiPath mit Ihrem Webhook-Anbieter und konfigurieren Sie die Webhook-Herausforderungsverifizierung oder die Header-basierte Authentifizierung.

Voraussetzungen

Ihr Webhook-Anbieter erfordert möglicherweise einen Handshake. Weitere Informationen zur Konfiguration der Herausforderungsverifizierung finden Sie im Abschnitt Verifizierung der Webhook-Herausforderung .

Je nachdem, wo Sie den Trigger erstellen, wird die generierte Webhook-URL entweder in der Aktivität HTTP Webhook Trigger oder auf der Seite Triggererstellung angezeigt, jedoch erst, nachdem die Verbindung erfolgreich erstellt wurde. Um Fehler zu vermeiden, fügen Sie die Webhook-URL in Ihre Anwendung ein , nachdem Sie Ihren Workflow veröffentlicht haben oder der Trigger erfolgreich im UiPath Orchestrator erstellt wurde.

Erstellen einer HTTP Webhook-Verbindung

1. Wählen Sie Orchestrator im Produktstartprogramm aus.

2. Wählen Sie einen Ordner aus und navigieren Sie dann zur Registerkarte Verbindungen .

3. Wählen Sie Verbindung hinzufügen aus.

4. Um die Seite zur Erstellung der Verbindung zu öffnen, wählen Sie den Konnektor in der Liste aus. Sie können die Suchleiste verwenden, um den Connector zu finden.

5. Geben Sie im Feld Für welche Anwendung ist dieser Webhook ein beschreibender Name für die Webhook-Anwendung ein, um leicht zu identifizieren, welchen Anbieter oder welche Integration diese Verbindung repräsentiert. Dieser Wert wird zum Verbindungsbezeichner.

6. (Optional) Konfigurieren Sie die header-basierte Authentifizierung.

   Wenn Sie möchten, dass UiPath jede eingehende Webhook-Anforderung validiert, wählen Sie im Dropdown- Menü Authentifizierungstyp die Option Header-basierte Authentifizierung aus und geben Sie dann Folgendes an:

   • Header-Schlüssel – Der HTTP-Header, den der Anbieter zum Senden der Anmeldeinformationen verwendet (z. B. X-API-Key oder X-API-Secret).
   • Header-Wert – der geheime Wert, den der Anbieter in diesem Header sendet (z. B. a1b2c3d4e5f6789...). Dieses Feld ist maskiert und sicher gespeichert. Sie können für dieses Feld auch ein Anmeldeinformations-Asset verwenden.

   Konfigurieren Sie denselben Headerschlüssel und -wert in den Webhook-Einstellungen des Anbieters. Wenn die Werte zur Laufzeit nicht übereinstimmen, weist UiPath die Anforderung mit HTTP 401 zurück.

   Weitere Informationen finden Sie unter Webhook-Header-Authentifizierung.

7. Konfigurieren Sie den Herausforderungsort
   Wählen Sie aus, wie der Anbieter das Herausforderungstoken sendet, damit UiPath richtig reagieren kann:

   • Keine Herausforderung – der Anbieter erfordert keinen Handshake und Sie können mit der Verbindung fortfahren.
   • Abfrageparameter (z. B. ?challenge=...)
   • JSON-Text (POST mit { "challenge": "..." })
   • Kopfzeile (z. B. X-Hub-Challenge)

8. Konfigurieren Sie die Herausforderungsverifizierung und stellen Sie eine Verbindung her
   Wenn der Anbieter einen Handshake erfordert, geben Sie die Herausforderungsverifizierung ein, die dem Muster des Anbieters entspricht ( welches Feld/jeder Header/ welche Abfrage gelesen werden soll und wie der Echo/validiert werden soll). Wenn die Konfiguration abgeschlossen ist, wählen Sie Verbinden aus.

   Wenn verfügbar, wählen Sie das Menü neben einem Feld und dann Anmeldeinformations-Asset verwenden oder Orchestrator-Asset verwenden aus , um auf ein Orchestrator-Asset zu verweisen, anstatt den Wert direkt einzugeben. Weitere Informationen finden Sie unter Verwenden von Anmeldeinformationsassets für Verbindungen.

Tipp:

• Verwenden Sie einen Namen, der den Anbieter und die Umgebung enthält (z. B. Stripe-prod oder Slack-staging), um Verwechslungen zu vermeiden.
• Wenn Sie nicht sicher sind, welches Herausforderungsmuster der Anbieter verwendet, überprüfen Sie seine Webhook-Dokumentation oder führen Sie eine Testregistrierung durch, um die Handshake-Anforderung zu überprüfen.

Überprüfung der Webhook-Herausforderung

Einige Anbieter erfordern, dass Webhook-URLs validiert werden, bevor sie mit dem Senden tatsächlicher Ereignisse beginnen. Dies geschieht mithilfe eines Herausforderungs-Antwort-Mechanismus. Wenn Sie einen Webhook registrieren, sendet der Anbieter eine spezielle Herausforderungsanforderung und der Endpunkt muss genau wie erwartet reagieren.

Der HTTP-Webhook-Connector unterstützt diese Verifizierungsabläufe über das Webhook-Herausforderungs-Framework, sodass Sie konfigurieren können, wie UiPath die Herausforderungen von Anbietern lesen und darauf reagieren soll.

Unterstützung der Herausforderungsverifizierung

UiPath unterstützt beide Arten von Webhook-Verhalten des Anbieters:

• Anbieter, die keine Herausforderungsverifizierung verwenden
• Anbieter, die vor der Aktivierung des Webhooks einen Herausforderungs-Handshake erfordern

Dies gewährleistet die Kompatibilität mit einfachen Webhook-Anbietern sowie mit Anbietern mit erweiterten Sicherheitsanforderungen.

Wenn Anbieter keine Herausforderungsverifizierung verwenden

Viele Anwendungen akzeptieren einfach eine Webhook-URL und beginnen sofort mit der Bereitstellung von Ereignissen.
Für diese Anbieter:

• Benutzer müssen lediglich eine Verbindung erstellen oder auswählen.
• Kopieren Sie die Webhook-URL.
• Fügen Sie ihn in die Webhook-Konfiguration des Anbieters ein.

Es sind keine zusätzlichen Schritte erforderlich. Der Webhook wird aktiv, sobald der Anbieter mit dem Senden von Ereignissen beginnt.

Das ist das häufigste und einfachste Szenario, das von UiPath nahtlos behandelt wird.

Wenn Anbieter eine Herausforderungsverifizierung erfordern

Einige Anbieter senden eine Herausforderungsanforderung , um die Webhook-URL zu überprüfen, bevor sie aktiviert werden.
In diesen Fällen:

• Benutzer müssen die Herausforderungsantwort in der HTTP Webhook-Verbindung konfigurieren .
• UiPath wartet auf die Herausforderungsanforderung des Anbieters.
• UiPath gibt basierend auf der Konfiguration automatisch den richtigen Herausforderungswert zurück.
• Sobald der Anbieter die Antwort validiert hat, beginnen normale Ereignisse zu fließen.

Da sich die Anbieter darin unterscheiden, wie sie die Herausforderung senden (Abfrageparameter, JSON-Text, Header usw.), ermöglicht die Konfiguration von UiPath den Benutzern, jedes dieser Muster zu verarbeiten.

Dies gewährleistet die Kompatibilität mit Webhook-Anbietern, die Sicherheits-Handshakes erzwingen, z. B. Slack, Meta (Facebook/Instagram), Stripe und anderen.

Konfigurieren der Herausforderungsverifizierung

Sie konfigurieren das Herausforderungsverhalten mit vier Parametern:

• Herausforderungsschlüssel
  Feld/Schlüssel mit dem Herausforderungswert. Wird zum Erkennen von Herausforderungsanforderungen verwendet ( darf nicht NULL sein).

• Herausforderungsort
  Wo der Schlüssel angezeigt wird:

  • Text
  • Abfrageparameter
  • Kopfzeile

• Inhaltstyp der Herausforderungsantwort
  Format der Antwort, die an den Anbieter zurückgegeben wird:

  • Text/Nur
  • application/json

• Antwortformat der Herausforderung
  Definiert, welcher Wert zurückgegeben wird (in der Regel der Herausforderungsschlüssel selbst).
  UiPath extrahiert den Wert aus der eingehenden Herausforderung und reagiert entsprechend.

Beispiele für die Herausforderungskonfiguration

Allgemeines Beispiel

Eingehende Anforderung

 {
  "challenge": "ABC123"
 }

Konfiguration

• Herausforderungsschlüssel: challenge != null
• Herausforderungsort: Textkörper
• Antworttyp: text/plain
• Antwortformat: challenge

Antwort

ABC123

Beispiel für die WhatsApp-Herausforderungsverifizierung

WhatsApp verwendet die abfrageparameterbasierte Herausforderungsmethode mit Hub.herausforderung.

Konfiguration

Parameter	Wert
Herausforderungsschlüssel	hub.challenge != null
Herausforderungsort	Abfrageparameter
Inhaltstyp der Herausforderungsantwort	text/plain
Antwortformat der Herausforderung	hub.challenge

Anbieteranfrage

GET https://your-webhook-url?hub.challenge=1234567890

Erwartete UiPath-Antwort

HTTP/1.1 200 OK
Content-Type: text/plain

1234567890

Dadurch wird der Besitz bestätigt und WhatsApp beginnt anschließend, echte Webhook-Ereignisse zu senden.

Zusammenfassung – Generisch im Vergleich zu WhatsApp

Schritt	Allgemeines Beispiel	WhatsApp-Beispiel
Herausforderungsort	Textkörper/Abfrage/Header	Abfrage
Tastenformat	Einfacher Schlüssel (z. B. challenge)	Schlüssel mit Punkt (hub.challenge )
ResponseType	text/nur oder application/json	Text/Nur
Antwortwert	Wert des Schlüssels	Wert von „ hub.challenge “
Method	POST oder GET	Nur GET

Beispiele nach Anbietermuster

Beispiel 1: Einfache Textabfrage mit Textantwort

Anbieter sendet

{"challenge":"abc123","type":"url_verification"}

Feld	Wert
Herausforderungsort	Body
Herausforderungsschlüssel	challenge
Inhaltstyp der Herausforderungsantwort	text
Antwortformat der Herausforderung	challenge

Antwort: abc123 (Text/Nur, 200)

Beispiel 2: Parameter-Herausforderung mit Textantwort

Anbieter sendet

GET /webhook?challenge=CHALLENGE_STRING

Feld	Wert
Herausforderungsort	Query Parameter
Herausforderungsschlüssel	challenge
Inhaltstyp der Herausforderungsantwort	text
Antwortformat der Herausforderung	challenge

Antwort: CHALLENGE_STRING (Text/Nur, 200)

Beispiel 3: Textabfrage mit JSON-Antwort

Anbieter sendet

{"challenge":"abc123"}

Feld	Wert
Herausforderungsort	Body
Herausforderungsschlüssel	challenge
Inhaltstyp der Herausforderungsantwort	json
Antwortformat der Herausforderung	{ "challenge": "challenge" }

Antwort: {"challenge":"abc123"} (application/json, 200)

Beispiel 4: Verschachtelter Textpfad (z. B. verification.token) mit Textantwort

Anbieter sendet

{"verification":{"token":"abc123"}}

Feld	Wert
Herausforderungsort	Body
Herausforderungsschlüssel	verification.token
Inhaltstyp der Herausforderungsantwort	text
Antwortformat der Herausforderung	verification.token

Antwort: abc123 (Text/Nur, 200)

Beispiel 5: Tief geschachtelter Pfad mit JSON-Antwort

Anbieter sendet

{"event":{"challenge":"abc123","type":"verify"}}

Feld	Wert
Herausforderungsort	Body
Herausforderungsschlüssel	event.challenge
Inhaltstyp der Herausforderungsantwort	json
Antwortformat der Herausforderung	{ "result": "event.challenge" }

Antwort: {"result":"abc123"} (application/json, 200)

Beispiel 6: Headerbasierte Herausforderung (Header-Name mit Bindestrich) mit Textantwort

Anbieter sendet

POST /webhook x-webhook-challenge: abc123

Feld	Wert
Herausforderungsort	Header
Herausforderungsschlüssel	"x-webhook-challenge"
Inhaltstyp der Herausforderungsantwort	text
Antwortformat der Herausforderung	"x-webhook-challenge"

Antwort: abc123 (Text/Nur, 200)

Hinweis:

Der Header-Name enthält Bindestriche, die in Analyse-Kontexten als Operatoren falsch interpretiert werden können. Das Einschließen des Bezeichners in doppelte Anführungszeichen (z. B. "x-webhook-challenge") stellt sicher, dass er als literale Schlüsselname behandelt wird. Verwenden Sie immer doppelte Anführungszeichen um einen Bezeichner, der Bindestriche, Punkte oder andere Sonderzeichen enthält.

Beispiel 7: Boolesche Erkennung mit unterschiedlichem Antwortschlüssel

Anbieter sendet

{"type":"url_verification","challenge":"abc","token":"legacytoken"}

Möchten Sie nach Feld type erkennen, antworten aber mit dem Wert challenge .

Feld	Wert
Herausforderungsort	body
Herausforderungsschlüssel	type == url_verification`
Inhaltstyp der Herausforderungsantwort	json
Antwortformat der Herausforderung	{ "challenge": "challenge" }

Antwort: {"challenge":"abc"} (application/json, 200)

Webhook-Header-Authentifizierung

Mit der Header-basierten Authentifizierung validiert UiPath jede eingehende Webhook-Anforderung anhand eines gemeinsamen Geheimnisses, das Sie bei der Verbindungserstellung konfiguriert haben. Dies verhindert, dass unbefugte Anrufer Ihre Workflows auslösen, indem sie an Ihre Webhook-URL posten.

Wie es funktioniert

Wenn die Header-basierte Authentifizierung für eine Verbindung aktiviert ist, führt Integration Service Folgendes aus:

1. Prüft jede eingehende Anforderung auf den konfigurierten Header-Schlüssel.
2. Akzeptiert das Ereignis, wenn der Header vorhanden ist und sein Wert mit dem gespeicherten Geheimnis übereinstimmt.
3. Gibt HTTP 401 Nicht autorisiert zurück und löst keinen Workflow aus, wenn der Header fehlt oder sein Wert nicht übereinstimmt.

Beispielanforderung, die UiPath akzeptiert:

POST /webhook HTTP/1.1
Host: <your-uipath-webhook-url>
X-API-Key: a1b2c3d4e5f6789...
Content-Type: application/json

{ "event": "..." }

Beispielanforderung, die UiPath abgelehnt (Header fehlt oder falscher Wert):

HTTP/1.1 401 Unauthorized

Konfigurationsfelder

In der folgenden Tabelle werden die Felder beschrieben, mit denen Sie die Webhook-Header-Authentifizierung auf dem Bildschirm zur Verbindungserstellung konfigurieren können.

Feld	Beschreibung	Beispiel
Authentifizierungstyp	Aktiviert oder deaktiviert die Header-Validierung für diese Verbindung.	Header Based Authentication / None
Header-Schlüssel	Name des HTTP-Headers, den der Anbieter sendet.	X-API-Key, X-API-Secret
Header-Wert	Geheimer Wert, den der Anbieter in diesem Header sendet. Im Ruhezustand maskiert.	a1b2c3d4e5f6789...

Kompatibilität des Anbieters

Die Header-basierte Authentifizierung funktioniert nur mit Anbietern, bei denen Sie einen benutzerdefinierten HTTP-Header für ausgehende Webhook-Bereitstellungen konfigurieren können.

Wenn Sie nicht sicher sind, ob Ihr Anbieter ausgehende benutzerdefinierte Header unterstützt, überprüfen Sie die Webhook-Dokumentation des Anbieters.

Aktualisieren oder Rotieren des Geheimnisses

Wenn Sie die Verbindung bearbeiten und den Headerwert ändern, wird der neue Wert sofort für alle Trigger wirksam, die diese Verbindung verwenden. Die Konfiguration des Anbieters muss gleichzeitig mit dem neuen Wert aktualisiert werden, andernfalls schlagen die Bereitstellungen des Anbieters mit HTTP 401 fehl, bis Sie dies tun.

Verhalten, wenn die Authentifizierung fehlschlägt

Eine Anforderung wird mit HTTP 401 Nicht autorisiert abgelehnt, wenn:

• Der erwartete Header fehlt in der Anforderung.
• Der Header ist vorhanden, aber sein Wert stimmt nicht mit dem gespeicherten Geheimnis überein.

Fehlgeschlagene Anforderungen werden von UiPath nicht wiederholt und es wird kein Triggerereignis ausgelöst. Es gilt das eigene Wiederholungsverhalten des Anbieters (falls vorhanden).

Ablaufverfolgungen von Authentifizierungsfehlern können im Abschnitt Ablaufverfolgungen angezeigt werden. Um unsere Systeme vor DoS-Angriffen zu schützen, sind die Traces von Authentifizierungsfehlern auf 5 pro Stunde begrenzt.

Wichtige Hinweise

• Die Header-basierte Authentifizierung ist verbindungsbezogenen. Alle Trigger, die für dieselbe Verbindung erstellt wurden, haben denselben Header-Schlüssel und -Wert – die Aktualisierung des Verbindungsgeheimnisses wirkt sich auf jeden Trigger aus, der sie verwendet.
• Die Header-basierte Authentifizierung ist unabhängig von der Herausforderungsüberprüfung. Entweder, beides oder keines kann für eine Verbindung aktiviert werden.
• Der Header-Wert wird verschlüsselt gespeichert und sollte mit der gleichen Vorsicht wie alle anderen Anmeldeinformationen behandelt werden.
• Bei Header-Namen wird gemäß der HTTP-Spezifikation die Groß-/Kleinschreibung nicht berücksichtigt (X-API-Key und x-api-key sind gleichwertig).