UiPath Documentation
integration-service
latest
false
Integration Service ユーザー ガイド
重要 :
このコンテンツの一部は機械翻訳によって処理されており、完全な翻訳を保証するものではありません。 Integration Service で提供されるコネクタ パッケージの一部は機械翻訳で処理されています。 新しいコンテンツの翻訳は、およそ 1 ~ 2 週間で公開されます。

HTTP Webhook 認証

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

前提条件​

Webhook プロバイダーによっては、ハンドシェイクが必要な場合があります。チャレンジ検証の設定方法の詳細については、「 Webhook チャレンジ検証 」セクションを参照してください。

トリガーを作成した場所に応じて、生成された Webhook URL は [HTTP Webhook トリガー] アクティビティまたはトリガーの作成ページに表示されますが、これはコネクションが正常に作成された後にのみです。失敗を避けるため、ワークフローのパブリッシュ後、または UiPath Orchestrator でトリガーが正常に作成された後に、アプリケーションに Webhook URL を貼り付けます。

HTTP Webhook 接続を作成する​

  1. 製品ランチャーから [Orchestrator] を選択します。

  2. フォルダーを選択して [ コネクション ] タブに移動します。

  3. [ コネクションを追加] を選択します。

  4. コネクション作成ページを開くには、リストからコネクタを選択します。検索バーを使用してコネクタを検索できます。

  5. [ この Webhook はどのアプリケーションですか ] フィールドに、Webhook アプリケーションのわかりやすい名前を入力します。これにより、このコネクションがどのベンダーまたは連携に属しているかを簡単に識別できます。この値が 接続識別子になります。

  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:

    • ヘッダー キー — ベンダーが資格情報を送信するために使用する HTTP ヘッダーです (例: X-API-Key や X-API-Secret)。
    • ヘッダー値 — ベンダーがそのヘッダーで送信するシークレット値です (例: a1b2c3d4e5f6789...)。このフィールドはマスクされ、安全に保存されます。このフィールドには資格情報アセットを使用することもできます。

    ベンダーの Webhook 設定で同じヘッダー キーと値を設定します。実行時に値が一致しない場合、UiPath は HTTP 401 で要求を拒否します。

    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. チャレンジの場所を設定する
    UiPath が正しく対応できるよう、ベンダーがチャレンジ トークンを送信する方法を選択します。

    • チャレンジなし - ベンダーはハンドシェイクを必要とせず、接続に進むことができます。
    • クエリ パラメーター (例: ?challenge=...)
    • JSON 本文 (POST と { "challenge": "..." })
    • ヘッダー (例: X-Hub-Challenge)
  8. 本人確認検証の設定と接続
    ベンダーがハンドシェイクを必要とする場合は、ベンダーのパターンに一致する チャレンジ検証 を入力します (読み取るフィールド/ヘッダー/クエリと、それをエコー/検証する方法)。設定が完了したら、[ 接続] を選択します。

    利用可能な場合は、フィールドの横にあるメニューを選択し、[ 資格情報アセットを使用 ] または [ Orchestrator アセットを使用 ] を選択して、値を直接入力するのではなく Orchestrator アセットを参照します。詳細については、「 コネクションに資格情報アセットを使用する」をご覧ください。

ヒント:
  • 混乱を避けるため、ベンダーと環境を含む名前 (Stripe-prod や Slack-staging など) を使用してください。
  • ベンダーが使用しているチャレンジ パターンがわからない場合は、ベンダーの Webhook ドキュメントを確認するか、テスト登録を実行してハンドシェイク リクエストを検査します。

Webhook チャレンジの検証​

一部のベンダーは、実際のイベントの送信を開始する前に、Webhook URL の検証を要求しています。これは、チャレンジ レスポンス メカニズムを使用して行われます。Webhook を登録すると、ベンダーは特別なチャレンジ要求を送信し、エンドポイントは期待どおりに正確に応答する必要があります。

HTTP Webhook コネクタは、 Webhook チャレンジ フレームワークを介してこれらの検証フローをサポートしており、UiPath がベンダーのチャレンジをどのように読み取って対応するかを設定できます。

チャレンジ検証のサポート​

UiPath では、ベンダー Webhook の両方の種類の動作がサポートされています。

  • チャレンジ検証を使用していないベンダー
  • Webhook をアクティブ化する前にチャレンジ ハンドシェイクを必要とするベンダー

これにより、単純な Webhook プロバイダーだけでなく、より高度なセキュリティ要件を持つプロバイダーにも対応できます。

ベンダーがチャレンジ検証​を使用しない場合

多くのアプリケーションは、Webhook URL を受け入れるだけで、すぐにイベントの配信を開始します。
これらのベンダーの場合:

  • ユーザーは 、コネクションを作成または選択するだけです。
  • Webhook URL をコピーします。
  • これをベンダーの Webhook 設定に貼り付けます。

追加の手順は不要です。Webhook は、ベンダーがイベントの送信を開始するとすぐにアクティブになります。

これは最も一般的でシンプルなシナリオであり、UiPath はシームレスに処理します。

ベンダー が チャレンジ検証を要求する場合​

一部のベンダーは、Webhook URL を有効化する前に、その URL を検証するための チャレンジ リクエスト を送信します。
これらのケースでは、次のようになります。

  • ユーザーは、HTTP Webhook 接続で チャレンジ応答を設定する必要があります 。
  • UiPath はベンダーのチャレンジ要求をリッスンします。
  • UiPath は、設定に基づいて正しいチャレンジ値を自動的に返します。
  • ベンダーが応答を検証すると、通常のイベントが流れ始めます。

チャレンジの送信方法 (クエリ パラメーター、JSON 本文、ヘッダーなど) はベンダーによって異なるため、UiPath の設定ではこれらのパターンをすべて処理できます。

これにより、Slack、Meta (Facebook/Instagram)、Stripe など、セキュリティ ハンドシェイクを適用する Webhook プロバイダーとの相互運用性が確保されます。

チャレンジ検証の設定​

チャレンジ動作は、次の 4 つのパラメーターを使用して設定します。

  • チャレンジ キー
    チャレンジ値を含むフィールド/キー。チャレンジ要求を検出するために使用します (null にすることはできません)。

  • チャレンジの場所
    キーが表示される場所:

    • 本文
    • クエリ パラメーター
    • ヘッダー
  • チャレンジ応答コンテンツの種類
    ベンダーに返される応答の形式:

    • テキスト/プレーン
    • application/json
  • チャレンジ応答の形式
    返される値を定義します (通常はチャレンジ キー自体)。
    UiPath は、受信したチャレンジから値を抽出し、それに応じて回答します。

チャレンジの設定例​

一般的な例​
受信要求​
 {
  "challenge": "ABC123"
 }
 {
  "challenge": "ABC123"
 }

構成

  • チャレンジキー: challenge != null
  • チャレンジ場所:ボディ
  • 応答の種類: text/plain
  • 応答の形式: challenge
レスポンス​

ABC123

WhatsAppチャレンジ検証の例​

WhatsApp は、 hub.challenge でクエリパラメータベースのチャレンジメソッドを使用します。

構成​
パラメーター値 (Value)
チャレンジ キーhub.challenge != null
チャレンジの場所クエリ パラメーター
チャレンジ応答コンテンツの種類text/plain
チャレンジ応答の形式hub.challenge
仕入先要求​

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

UiPath の期待される回答​
HTTP/1.1 200 OK
Content-Type: text/plain

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

1234567890

これにより所有権が確認され、WhatsAppはその後、実際のWebhookイベントの送信を開始します。

概要—ジェネリックとWhatsApp​
手順一般的な例WhatsAppの例
チャレンジの場所本文/クエリ/ヘッダークエリ
キーフォーマット単純キー (例: challenge)ドット付きのキー ("hub.challenge")
応答の種類text/plain または application/jsonテキスト/プレーン
応答値キーの値値 "hub.challenge"
メソッドPOST または GETGET のみ

ベンダー パターン別の例​

例1:テキスト応答を伴う単純なボディチャレンジ​
ベンダーが送信する​

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

フィールド値 (Value)
チャレンジの場所Body
チャレンジ キーchallenge
チャレンジ応答のコンテンツの種類text
チャレンジの応答形式challenge

応答: abc123 (テキスト/プレーン、200)

例 2: テキスト応答によるクエリ パラメーター チャレンジ​
ベンダーが送信する​

GET /webhook?challenge=CHALLENGE_STRING

フィールド値 (Value)
チャレンジの場所Query Parameter
チャレンジ キーchallenge
チャレンジ応答のコンテンツの種類text
チャレンジの応答形式challenge

応答: CHALLENGE_STRING (テキスト/プレーン、200)

例 3: JSON 応答を使用したボディ チャレンジ​
ベンダーが送信する​

{"challenge":"abc123"}

フィールド値 (Value)
チャレンジの場所Body
チャレンジ キーchallenge
チャレンジ応答のコンテンツの種類json
チャレンジの応答形式{ "challenge": "challenge" }

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

例 4: テキスト応答の​を含む入れ子になった本文パス (例: verification.token
ベンダーが送信する​

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

フィールド値 (Value)
チャレンジの場所Body
チャレンジ キーverification.token
チャレンジ応答のコンテンツの種類text
チャレンジの応答形式verification.token

応答: abc123 (テキスト/プレーン、200)

例 5: JSON 応答を含む深く入れ子になったパス​
ベンダーが送信する​

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

フィールド値 (Value)
チャレンジの場所Body
チャレンジ キーevent.challenge
チャレンジ応答のコンテンツの種類json
チャレンジの応答形式{ "result": "event.challenge" }

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

例 6: テキスト応答を含むヘッダーベースのチャレンジ (ハイフンでつながれたヘッダー名)​
ベンダーが送信する​

POST /webhook x-webhook-challenge: abc123

フィールド値 (Value)
チャレンジの場所Header
チャレンジ キー"x-webhook-challenge"
チャレンジ応答のコンテンツの種類text
チャレンジの応答形式"x-webhook-challenge"

応答: abc123 (テキスト/プレーン、200)

注:

ヘッダー名にはハイフンが含まれています。これは、解析コンテキストで演算子と誤解される可能性があります。識別子を二重引用符で囲むと (例: "x-webhook-challenge") リテラルキー名として扱われます。ハイフン、ドット、その他の特殊文字を含む識別子は、必ず二重引用符で囲んでください。

例 7: 異なる応答キーによるブール値検出​
ベンダーが送信する​

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

typeフィールドで検出したいが、challenge値で応答したい。

フィールド値 (Value)
チャレンジの場所body
チャレンジ キーtype == url_verification」
チャレンジ応答のコンテンツの種類json
チャレンジの応答形式{ "challenge": "challenge" }

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

Webhook ヘッダー認証​

ヘッダーベースの認証では、UiPath はすべての受信 Webhook 要求を、接続の作成時に設定した共有シークレットに対して検証できます。これにより、権限のない呼び出し元が Webhook URL に投稿してワークフローをトリガーするのを防ぎます。

動作のしくみ​

コネクションでヘッダーベースの認証が有効化されている場合、Integration Service は以下を行います。

  1. すべての受信要求をチェックし、設定されているヘッダー キーを確認します。
  2. ヘッダーが存在していて、その値が格納されているシークレットと一致する場合、イベントを受け入れます。
  3. HTTP 401 Unauthorized を返します。ヘッダーがない場合、またはその値が一致しない場合は、ワークフローをトリガーしません。

Webhook ヘッダー認証

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

UiPath が拒否した要求の例 (ヘッダーが見つからないか、値が正しくありません)

HTTP/1.1 401 Unauthorized
HTTP/1.1 401 Unauthorized

設定フィールド​

次の表で、接続の作成画面で Webhook ヘッダー認証を設定できるフィールドについて説明します。

フィールド説明例
認証の種類この接続のヘッダー検証を有効化または無効化します。Header Based Authentication / None
ヘッダー キーベンダーが送信する HTTP ヘッダーの名前です。X-API-Key, X-API-Secret
ヘッダー値ベンダーがそのヘッダーで送信するシークレット値です。安静時にマスクをしています。a1b2c3d4e5f6789...

ベンダーの相互運用性​

ヘッダーベースの認証は、送信 Webhook 配信時にカスタム HTTP ヘッダーを設定できるベンダーでのみ機能します。

ベンダーが送信カスタム ヘッダーをサポートしているかどうかが不明な場合は、ベンダーの Webhook ドキュメントをご覧ください。

シークレットを更新またはローテーションする​

コネクションを編集してヘッダーの値を変更すると、そのコネクションを使用するすべてのトリガーに対して新しい値が直ちに有効になります。同時にベンダーの設定を新しい値で更新する必要があります。更新しないと、更新するまでベンダーの配信は HTTP 401 で失敗します。

認証に失敗した場合の動作​

次の場合、 要求は HTTP 401 Unauthorized で拒否されます。

  • 予期されるヘッダーが要求に存在しない。
  • ヘッダーは存在しますが、その値が格納されているシークレットと一致しません。

失敗した要求は UiPath によってリトライされず、トリガー イベントはディスパッチされません。ベンダー独自のリトライ動作 (ある場合) が適用されます。

認証失敗のトレースは、[ トレース] セクションで確認できます。DoS 攻撃からシステムを保護するため、認証失敗トレースは 1 時間あたり 5 回までに制限されています。

重要​

  • ヘッダーベースの認証は、 接続をスコープします。同じコネクションに対して作成されたトリガーはすべて同じヘッダー キーと値を共有します。コネクションのシークレットを更新すると、そのシークレットを使用するすべてのトリガーに影響します。
  • ヘッダーベースの認証は、 チャレンジ検証とは無関係です。コネクションで有効化することは、両方を有効にすることも、どちらも有効化できません。
  • ヘッダー値は暗号化されて保存されるため、他の資格情報と同様に慎重に扱う必要があります。
  • ヘッダー名は、HTTP 仕様に従って大文字と小文字を区別しません (X-API-Key と x-api-key は同一です)。

Webhook JWT authentication​

注:

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.

フィールド説明例
認証の種類Select JWT Authentication to validate a JWT on every request for this connection.JWT Authentication
キーの種類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​

キーの種類キーAlgorithms
PassphraseShared secretHS256HS384、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:

原因メッセージ
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.

このページは役に立ちましたか?

接続

ヘルプ リソース サポート(opens in new window)

学習する UiPath アカデミー(opens in new window)

質問する UiPath フォーラム(opens in new window)

最新情報を取得