UiPath Documentation
integration-service
latest
false
Guide de l'utilisateur d'Integration Service
Important :
Ce contenu a été traduit à l'aide d'une traduction automatique. Les packages de connecteurs disponibles dans Integration Service sont traduits à l'aide d'un moteur de traduction. La localisation du contenu nouvellement publié peut prendre 1 à 2 semaines avant d’être disponible.

Authentification HTTP Webhook

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

Prérequis​

Votre fournisseur de Webhook peut avoir besoin d’établir une liaison. Reportez-vous à la section Vérification du défi de webhook pour plus de détails sur la façon de configurer la vérification des défis.

Selon l’endroit où vous créez le déclencheur, l’URL du webhook générée apparaîtra dans l’activité de déclencheur HTTP Webhook ou sur la page de création du déclencheur, mais uniquement après la création de la connexion avec succès. Pour éviter les échecs, collez l’URL du webhook dans votre application après avoir publié votre workflow, ou bien le déclencheur a été créé avec succès dans UiPath Orchestrator.

Création d'une connexion HTTP Webhook​

  1. Sélectionnez Orchestrator dans le lanceur du produit.

  2. Sélectionnez un dossier, puis accédez à l'onglet Connexions .

  3. Sélectionnez Ajouter une connexion (Add connecion).

  4. Pour ouvrir la page de création de connexion, sélectionnez le connecteur dans la liste. Vous pouvez utiliser la barre de recherche pour trouver le connecteur.

  5. Dans le champ Pour quelle application est ce Webhook , saisissez un nom descriptif pour l’application de Webhook, quelque chose qui facilite l’identification du fournisseur ou de l’intégration que cette connexion représente. Cette valeur devient l' identificateur de connexion.

  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:

    • Clé d'en-tête — l'en-tête HTTP utilisé par le fournisseur pour envoyer les informations d'identification (par exemple, X-API-Key ou X-API-Secret).
    • Valeur de l’en-tête — la valeur du secret que le fournisseur envoie dans cet en-tête (par exemple, a1b2c3d4e5f6789...). Ce champ est masqué et stocké en toute sécurité. Vous pouvez également utiliser une ressource d'informations d’identification pour ce champ.

    Configurez la même clé et la même valeur d’en-tête dans les paramètres du webhook du fournisseur. Si les valeurs ne correspondent pas au moment du runtime, UiPath rejettera la requête avec HTTP 401.

    Pour plus d'informations, consultez Authentification de l'en-tête Webhook.

    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. Configurer l'emplacement du défi
    Choisissez la façon dont le fournisseur enverra le jeton de défi afin qu'UiPath puisse répondre correctement :

    • Aucun défi : le fournisseur n'a pas besoin d'établir la liaison et vous pouvez procéder à la connexion.
    • Paramètre de requête (par exemple, ?challenge=...)
    • Corps JSON (PUBLIER avec { "challenge": "..." })
    • En-tête (par ex., X-Hub-Challenge)
  8. Configurer la vérification du défi et se connecter
    Si le fournisseur requiert un processus d'établissement de liaison, saisissez la vérification de défi qui correspond au modèle du fournisseur (le champ/l'en-tête/la requête à lire et comment l'écho/la valider). Une fois la configuration terminée, sélectionnez Connecter.

    Lorsque cette option est disponible, sélectionnez le menu à côté d'un champ et choisissez Utiliser la ressource d'informations d’identification ou Utiliser la ressource Orchestrator pour référencer une ressource Orchestrator au lieu d'entrer directement la valeur. Pour plus d'informations, consultez Utiliser des ressources d'informations d'identification pour les connexions.

Astuce :
  • Utilisez un nom qui inclut le fournisseur et l’environnement (par exemple, Stripe-prod ou Slack-staging) pour éviter toute confusion.
  • Si vous ne savez pas quel modèle de défi le fournisseur utilise, vérifiez les documents de son webhook ou exécutez un enregistrement de test pour inspecter la demande d'établissement de liaison.

Vérification du défi de webhook​

Certains fournisseurs exigent que les URL du webhook soient validées avant de commencer à envoyer des événements réels. Cela se fait à l'aide d'un mécanisme de défi-réponse. Lorsque vous enregistrez un webhook, le fournisseur envoie une demande de défi spécial et le point de terminaison doit répondre exactement comme prévu.

Le connecteur HTTP Webhook prend en charge ces flux de vérification via l' infrastructure des défis Webhook, vous permettant de configurer la façon dont UiPath doit lire et répondre aux défis des fournisseurs.

Prise en charge de la vérification des défis​

UiPath prend en charge les deux types de comportements Webhooks des fournisseurs :

  • Fournisseurs qui n’utilisent pas la vérification des défis
  • Les fournisseurs qui ont besoin d’établir une liaison de défi avant d’activer le Webhook

Cela garantit la compatibilité avec les fournisseurs de webhooks simples ainsi que ceux avec des exigences de sécurité plus avancées.

Lorsque les fournisseurs n'utilisent pas la vérification des défis​

De nombreuses applications acceptent simplement une URL de webhook et commencent immédiatement à fournir des événements.
Pour ces fournisseurs :

  • Les utilisateurs n'ont qu'à créer ou sélectionner une connexion.
  • Copiez l’ URL du webhook.
  • Collez-le dans la configuration du webhook du fournisseur.

Aucune étape supplémentaire n'est nécessaire. Le Webhook devient actif dès que le fournisseur commence à envoyer des événements.

Il s'agit du scénario le plus courant et le plus simple, et UiPath le gère de manière transparente.

Lorsque les fournisseurs ont besoin de vérification des difficultés​

Certains fournisseurs envoient une requête de défi pour vérifier l’URL du webhook avant de l’activer.
Dans ces cas :

  • Les utilisateurs doivent configurer la réponse au défi dans la connexion HTTP Webhook.
  • UiPath écoute la demande de défi du fournisseur.
  • UiPath renvoie automatiquement la valeur de défi correcte en fonction de la configuration.
  • Une fois que le fournisseur a validé la réponse, les événements normaux commencent à se produire.

Étant donné que les fournisseurs diffèrent dans la façon dont ils envoient le défi (paramètre de requête, corps JSON, en-tête, etc.), la configuration de UiPath permet aux utilisateurs de gérer n'importe lequel de ces modèles.

Cela garantit la compatibilité avec les fournisseurs de Webhooks qui appliquent les liaisons de sécurité tels que Slack, Meta (Facebook/Instangram), Stripe et autres.

Configurer la vérification des défis​

Vous pouvez configurer le comportement au défi à l'aide de quatre paramètres :

  • Clé de défi
    Champ/clé contenant la valeur du défi. Utilisé pour détecter les requêtes de défi.

  • Emplacement du défi
    Où la clé apparaît :

    • Corps
    • Paramètre de requête
    • En-tête
  • Type de contenu de réponse de défi
    Format de la réponse renvoyée au fournisseur :

    • texte/Brute
    • application/json
  • Format de réponse de défi
    Définit la valeur renvoyée (en général la clé de défi elle-même).
    UiPath extrait la valeur du défi entrant et répond en conséquence.

Exemples de configuration de défis​

Exemple générique​
Demande entrante​
 {
  "challenge": "ABC123"
 }
 {
  "challenge": "ABC123"
 }

Configuration

  • Clé de défi : challenge != null
  • Emplacement du défi : Corps
  • Type de réponse : text/plain
  • Format de réponse : challenge
Réponse​

ABC123

Exemple de vérification de défi Whatsapp​

WhatsApp utilise la méthode de défi basée sur les paramètres de requête avec hub.challenge.

Configuration​
ParamètreValeur (Value)
Clé de défihub.challenge != null
Emplacement du défiParamètre de requête
Type de contenu de réponse de défitext/plain
Format de réponse de défihub.challenge
Demande du fournisseur​

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

Réponse attendue d’UiPath​
HTTP/1.1 200 OK
Content-Type: text/plain

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

1234567890

Cela confirme la propriété et WhatsApp commencera par la suite à envoyer de vrais événements de webhook.

Résumé — Générique et Whatsapp​
ÉtapeExemple génériqueExemple de Whatsapp
Emplacement du défiCorps/Requête/En-têteRequête
Format de cléClé simple (par exemple, challenge)Clé avec un point "hub.challenge")
ResponseTypetexte/IA ou application/jsontexte/Brute
Valeur de la réponseValeur de la cléValeur de "hub.challenge"
MethodPOST ou GETOBTENIR uniquement

Exemples par modèle de fournisseur​

Exemple 1 : un défi de corps simple avec une réponse textuelle​
Envois du fournisseur​

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

ChampValeur (Value)
Emplacement du défiBody
Clé de défichallenge
Type de contenu de la réponse du défitext
Format de la réponse de défichallenge

Réponse : abc123 (texte/Brut, 200)

Exemple 2 : défi de paramètre de requête avec réponse textuelle​
Envois du fournisseur​

GET /webhook?challenge=CHALLENGE_STRING

ChampValeur (Value)
Emplacement du défiQuery Parameter
Clé de défichallenge
Type de contenu de la réponse du défitext
Format de la réponse de défichallenge

Réponse : CHALLENGE_STRING (texte/Brut, 200)

Exemple 3 : défi du corps avec réponse JSON​
Envois du fournisseur​

{"challenge":"abc123"}

ChampValeur (Value)
Emplacement du défiBody
Clé de défichallenge
Type de contenu de la réponse du défijson
Format de la réponse de défi{ "challenge": "challenge" }

Réponse : {"challenge":"abc123"} (application/json, 200)

Exemple 4 : chemin d'accès au corps imbriqué (par exemple, verification.token) avec la réponse textuelle​
Envois du fournisseur​

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

ChampValeur (Value)
Emplacement du défiBody
Clé de défiverification.token
Type de contenu de la réponse du défitext
Format de la réponse de défiverification.token

Réponse : abc123 (texte/Brut, 200)

Exemple 5 : Chemin profondément imbriqué avec réponse JSON​
Envois du fournisseur​

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

ChampValeur (Value)
Emplacement du défiBody
Clé de défievent.challenge
Type de contenu de la réponse du défijson
Format de la réponse de défi{ "result": "event.challenge" }

Réponse : {"result":"abc123"} (application/json, 200)

Exemple 6 : un défi basé sur une en-tête avec une réponse textuelle​
Envois du fournisseur​

POST /webhook x-webhook-challenge: abc123

ChampValeur (Value)
Emplacement du défiHeader
Clé de défi"x-webhook-challenge"
Type de contenu de la réponse du défitext
Format de la réponse de défi"x-webhook-challenge"

Réponse : abc123 (texte/Brut, 200)

Remarque :

Le nom de l’en-tête contient des traits d’union, qui peuvent être interprétés comme des opérateurs dans l’analyse des contextes. L'encapsulage de l'identifiant dans des guillemets doubles (par exemple, "x-webhook-challenge") garantit qu'il est traité comme un nom de clé littérale. Utilisez toujours des guillemets doubles autour d'un identifiant contenant des traits d'union, des points ou d'autres caractères spéciaux.

Exemple 7 : détection booléenne avec une clé de réponse différente​
Envois du fournisseur​

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

Souhaitez-vous détecter par le champ type , mais répondez avec la valeur challenge .

ChampValeur (Value)
Emplacement du défibody
Clé de défitype == vérification_URL
Type de contenu de la réponse du défijson
Format de la réponse de défi{ "challenge": "challenge" }

Réponse : {"challenge":"abc"} (application/json, 200)

Authentification de l'en-tête de Webhook​

L’authentification basée sur l’en-tête permet à UiPath de valider chaque demande de Webhook entrant par rapport à une clé secrète partagée que vous avez configurée lors de la création de la connexion. Cela empêche les appelants non autorisés de déclencher vos workflows en publiant votre URL Webhook.

Mode de fonctionnement​

Lorsque l’authentification basée sur l’en-tête est activée sur une connexion, Integration Service:

  1. Vérifie chaque demande entrante pour la clé d'en-tête configurée.
  2. Accepte l’événement si l’en-tête est présent et que sa valeur correspond au secret stocké.
  3. Renvoie HTTP 401 Non autorisé et ne déclenche aucun workflow si l'en-tête est absent ou si sa valeur ne correspond pas.

Authentification de l'en-tête Webhook

Exemple de requête acceptée par UiPath:

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

Exemple de requête rejetée par UiPath (en-tête manquant ou valeur incorrecte):

HTTP/1.1 401 Unauthorized
HTTP/1.1 401 Unauthorized

Champs de configuration​

Le tableau suivant décrit les champs qui permettent de configurer l'authentification de l'en-tête Webhook sur l'écran de création de la connexion.

ChampDescriptionExemple
Type d’authentificationActive ou désactive la validation des en-têtes pour cette connexion.Header Based Authentication / None
Clé d’en-têteNom de l’en-tête HTTP envoyé par le fournisseur.X-API-Key, X-API-Secret
Valeur de l’en-têteLa valeur secrète que le fournisseur envoie dans cet en-tête. Masqué au repos.a1b2c3d4e5f6789...

Compatibilité des fournisseurs​

L’authentification basée sur l’en-tête ne fonctionne qu’avec les fournisseurs qui vous permettent de configurer un en-tête HTTP personnalisé sur les livraisons de webhook sortantes.

Si vous ne savez pas si votre fournisseur prend en charge les en-têtes personnalisés sortants, consultez la documentation Webhook du fournisseur.

Mise à jour ou rotation de la clé secrète​

Lorsque vous modifiez la connexion et modifiez la valeur de l'en-tête, la nouvelle valeur prend effet immédiatement pour tous les déclencheurs utilisant cette connexion. La configuration du fournisseur doit être mise à jour avec la nouvelle valeur au même moment, ou les livraisons du fournisseur échoueront avec HTTP 401 tant que vous ne le faireez pas.

Comportement en cas d’échec de l’authentification​

Une demande est rejetée avec HTTP 401 Non autorisé si:

  • L'en-tête attendu est absent de la requête.
  • L’en-tête est présent, mais sa valeur ne correspond pas à la clé secrète stockée.

Les demandes échouées ne sont pas réessayées par UiPath et aucun événement de déclencheur n’est envoyé. Le propre comportement de réessai du fournisseur (le cas échéant) s'applique.

Les traçages d'échec d'authentification peuvent être consultés dans la section Traçages . Pour aider à protéger nos systèmes contre les attaques DoS, les traces d'échec d'authentification sont limitées à 5 par heure.

Remarque importante​

  • L'authentification basée sur l'en-tête est définie sur l'étendue de la connexion. Tous les déclencheurs créés pour la même connexion partagent la même clé et la même valeur d'en-tête; la mise à jour du secret de la connexion affecte chaque déclencheur qui l'utilise.
  • L’authentification basée sur l’en-tête est indépendante de la vérification des défis. L’une ou l’autre, les deux, ou l’aucune ne peut être activée sur une connexion.
  • La valeur de l’en-tête est stockée chiffrée et doit être gérée avec la même attention que tout autre identifiant.
  • Les noms d’en-tête ne sont pas sensibles à la casse selon la spécification HTTP (X-API-Key et x-api-key sont équivalents).

Webhook JWT authentication​

Remarque :

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.

ChampDescriptionExemple
Type d’authentificationSelect JWT Authentication to validate a JWT on every request for this connection.JWT Authentication
TypeCléHow 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​

TypeCléClé (Key)Algorithms
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:

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

Cette page vous a-t-elle été utile ?

Connecter

Besoin d'aide ? Assistance(opens in new window)

Vous souhaitez apprendre ? UiPath Academy(opens in new window)

Vous avez des questions ? UiPath Forum(opens in new window)

Rester à jour