HTTP Webhook 認証

UiPath を Webhook プロバイダーに接続し、Webhook チャレンジの検証またはヘッダーベースの認証を設定します。

前提条件

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

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

HTTP Webhook 接続を作成する

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

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

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

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

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

6. (任意) ヘッダーベースの認証を設定します。

   すべての受信 Webhook 要求を UiPath で検証する場合は、[ 認証の種類 ] ドロップダウンから [ ヘッダー ベースの認証] を選択し、以下を指定します。

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

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

   詳細については、「 Webhook ヘッダー認証」をご覧ください。

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 != 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

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

概要—ジェネリックとWhatsApp

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

ベンダー パターン別の例

例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 を返します。ヘッダーがない場合、またはその値が一致しない場合は、ワークフローをトリガーしません。

UiPath が受け入れる要求の例:

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

設定フィールド

次の表で、接続の作成画面で 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 は同一です)。