UiPath Documentation
integration-service
latest
false
Integration Service-Benutzerhandbuch
Wichtig :
Dieser Inhalt wurde maschinell übersetzt. Die Connector-Pakete, die in Integration Service verfügbar sind, werden maschinell übersetzt. Es kann 1–2 Wochen dauern, bis die Lokalisierung neu veröffentlichter Inhalte verfügbar ist.

HTTP Webhook-Authentifizierung

Connect UiPath to your webhook provider and configure webhook challenge verification, header-based authentication, or JWT authentication.

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) Configure authentication.

    If you want UiPath to validate every incoming webhook request, select a method from the Authentication Type dropdown.

    For Header Based Authentication, specify:

    • 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.

    For JWT Authentication, specify:

    • Key type — select Passphrase to verify tokens with a shared secret, or PEM Key to verify them with a public key.
    • JWT secret (for Passphrase) — the shared secret that the sender uses to sign the token.
    • JWT public key (for PEM Key) — the PEM-encoded public key that verifies the token signature, including the BEGIN and END lines.
    • JWT algorithm — the algorithm that the sender uses to sign the token. The default is HS256 for Passphrase and RS256 for PEM Key.

    The sender must send a signed JWT in the Authorization: Bearer <your-access-token> header of every request. If the token is missing, not valid, or expired, UiPath rejects the request with HTTP 401.

    For more information, see Webhook JWT authentication.

  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"
 }
 {
  "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​
ParameterWert
Herausforderungsschlüsselhub.challenge != null
HerausforderungsortAbfrageparameter
Inhaltstyp der Herausforderungsantworttext/plain
Antwortformat der Herausforderunghub.challenge
Anbieteranfrage​

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

Erwartete UiPath-Antwort​
HTTP/1.1 200 OK
Content-Type: text/plain

1234567890
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​
SchrittAllgemeines BeispielWhatsApp-Beispiel
HerausforderungsortTextkörper/Abfrage/HeaderAbfrage
TastenformatEinfacher Schlüssel (z. B. challenge)Schlüssel mit Punkt (hub.challenge )
ResponseTypetext/nur oder application/jsonText/Nur
AntwortwertWert des SchlüsselsWert von „ hub.challenge “
MethodPOST oder GETNur GET

Beispiele nach Anbietermuster​

Beispiel 1: Einfache Textabfrage mit Textantwort​
Anbieter sendet​

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

FeldWert
HerausforderungsortBody
Herausforderungsschlüsselchallenge
Inhaltstyp der Herausforderungsantworttext
Antwortformat der Herausforderungchallenge

Antwort: abc123 (Text/Nur, 200)

Beispiel 2: Parameter-Herausforderung mit Textantwort​
Anbieter sendet​

GET /webhook?challenge=CHALLENGE_STRING

FeldWert
HerausforderungsortQuery Parameter
Herausforderungsschlüsselchallenge
Inhaltstyp der Herausforderungsantworttext
Antwortformat der Herausforderungchallenge

Antwort: CHALLENGE_STRING (Text/Nur, 200)

Beispiel 3: Textabfrage mit JSON-Antwort​
Anbieter sendet​

{"challenge":"abc123"}

FeldWert
HerausforderungsortBody
Herausforderungsschlüsselchallenge
Inhaltstyp der Herausforderungsantwortjson
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"}}

FeldWert
HerausforderungsortBody
Herausforderungsschlüsselverification.token
Inhaltstyp der Herausforderungsantworttext
Antwortformat der Herausforderungverification.token

Antwort: abc123 (Text/Nur, 200)

Beispiel 5: Tief geschachtelter Pfad mit JSON-Antwort​
Anbieter sendet​

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

FeldWert
HerausforderungsortBody
Herausforderungsschlüsselevent.challenge
Inhaltstyp der Herausforderungsantwortjson
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

FeldWert
HerausforderungsortHeader
Herausforderungsschlüssel"x-webhook-challenge"
Inhaltstyp der Herausforderungsantworttext
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 .

FeldWert
Herausforderungsortbody
Herausforderungsschlüsseltype == url_verification`
Inhaltstyp der Herausforderungsantwortjson
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.

Webhook-Header-Authentifizierung

Beispielanforderung, die UiPath akzeptiert:

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

{ "event": "..." }
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
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.

FeldBeschreibungBeispiel
AuthentifizierungstypAktiviert oder deaktiviert die Header-Validierung für diese Verbindung.Header Based Authentication / None
Header-SchlüsselName des HTTP-Headers, den der Anbieter sendet.X-API-Key, X-API-Secret
Header-WertGeheimer 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).

Webhook JWT authentication​

Hinweis:

JWT authentication, query parameter filters, and the query parameter outputs are available only in Automation Cloud.

JWT authentication lets UiPath validate every incoming webhook request with a signed JSON Web Token (JWT). The sender signs a token with a secret or a private key and sends it in the Authorization header. UiPath verifies the token with the key that you configured on the connection. Unlike a static header value, a token expires, so a leaked token stops working after its expiration time.

How JWT authentication works​

When JWT authentication is enabled on a connection, Integration Service does these checks on every incoming request, including challenge requests:

  1. Reads the token from the Authorization: Bearer <your-access-token> header.
  2. Verifies the token signature with the key and the algorithm configured on the connection.
  3. Checks that the token has an exp (expiration time) claim and that the token has not expired. If the token has an nbf (not before) claim, UiPath accepts the token only after that time.
  4. Accepts the event if all the checks pass. If a check fails, UiPath returns HTTP 401 Unauthorized and does not trigger any workflow.
Example request that UiPath accepts​
POST /<organization>/<tenant-id>/elements_/v1/webhooks/events/<webhook-id> HTTP/1.1
Host: cloud.uipath.com
Authorization: Bearer <your-access-token>
Content-Type: application/json

{ "event": "..." }
POST /<organization>/<tenant-id>/elements_/v1/webhooks/events/<webhook-id> HTTP/1.1
Host: cloud.uipath.com
Authorization: Bearer <your-access-token>
Content-Type: application/json

{ "event": "..." }

JWT configuration fields​

The following table describes the fields that let you configure webhook JWT authentication on the connection creation screen.

FeldBeschreibungBeispiel
AuthentifizierungstypSelect JWT Authentication to validate a JWT on every request for this connection.JWT Authentication
TastentypHow UiPath verifies the token signature. Passphrase uses a shared secret. PEM Key uses a public key.Passphrase / PEM Key
JWT secretShown when Key type is Passphrase. The shared secret that the sender uses to sign the token.A random value of 32 or more characters
JWT public keyShown when Key type is PEM Key. The PEM-encoded RSA or EC public key that verifies the signature, including the BEGIN and END lines.-----BEGIN PUBLIC KEY----- ... -----END PUBLIC KEY-----
JWT algorithmThe algorithm that the sender uses to sign the token. It must match the key type.HS256 (default for Passphrase), RS256 (default for PEM Key)

Supported algorithms​

TastentypSchlüsselAlgorithms
PassphraseShared secretHS256, HS384, HS512
PEM KeyRSA public keyRS256, RS384, RS512, PS256, PS384, PS512
PEM KeyEC public keyES256 (P-256), ES384 (P-384), ES512 (P-521)

UiPath uses only the algorithm configured on the connection. The alg value in the token header must match it. UiPath always rejects unsigned tokens (alg: none).

For Passphrase, use a random secret of at least 32 characters for HS256, 48 characters for HS384, or 64 characters for HS512.

For PEM Key, keep the private key with the sender and paste only the public key into the connection. If the JWT public key field contains a private key, every request fails authentication.

Token requirements​

The sender must:

  • Send the token in the Authorization header with the Bearer scheme. UiPath does not read tokens from query parameters or from other headers.
  • Sign the token with the configured key and algorithm.
  • Include an exp claim in the token. UiPath rejects tokens that do not have an exp claim.

UiPath does not check other claims, such as iss, aud, or sub. There is no grace period for the exp and nbf claims, so make sure that the clock of the sender is accurate.

Vendor compatibility for JWT authentication​

JWT authentication works only with senders that can create a signed JWT and send it in the Authorization header of each webhook request. For example, your own service or an integration platform that you control. If you are not sure, check the webhook documentation of the sender.

JWT authentication failures​

UiPath rejects a request with HTTP 401 Unauthorized if:

  • The Authorization header is absent, or it does not use the Bearer scheme.
  • The token signature does not match the configured key, or the token uses a different algorithm.
  • The token does not have an exp claim, has expired, or is used before its nbf time.
  • The JWT settings of the connection are not valid. For example, the algorithm does not match the key type, or the JWT public key field does not contain a PEM-encoded public key.

UiPath does not check the JWT settings when you create the connection. An incorrect setting shows only when requests start to fail.

The response contains one of these messages:

UrsacheMeldung
No bearer token in the requestAuthentication failed. The request did not include a bearer token in the Authorization header.
All other failuresAuthentication failed. The bearer token in the Authorization header is invalid or expired.

Failed requests are not retried by UiPath, and no trigger event is dispatched. Authentication failure traces work the same way as for header-based authentication. For details, see Behavior when authentication fails.

The token in the trigger output​

After UiPath verifies a token, it masks the token in the event. In the output of the HTTP Webhook trigger and of the Get Trigger Event Output activity, the Authorization header keeps only the first five characters of the token, for example Bearer eyJhb*****. This prevents a person who can read the event from using the token again.

JWT important notes​

  • JWT authentication is connection-scoped. All triggers created against the same connection use the same key — updating the connection's key affects every trigger using it.
  • When you change the key on the connection, update the sender at the same time. Tokens signed with the old key fail authentication.
  • UiPath checks the token on every request, including challenge requests. If your vendor sends a challenge request, the challenge request must also contain a valid token.
  • Store the JWT secret with the same care as any other credential.

War diese Seite hilfreich?

Verbinden

Benötigen Sie Hilfe? Support(opens in new window)

Möchten Sie lernen? UiPath Academy(opens in new window)

Haben Sie Fragen? UiPath-Forum(opens in new window)

Auf dem neuesten Stand bleiben