Webhook

Webhook を使用すると、UiPath のオートメーションをお使いのアプリケーションエコシステム全体とより適切に統合できます。これにより、Orchestrator イベントをサブスクライブして、任意の外部 DCM、BPM、CRM ソリューションに送信できます。また、処理可能な新しいキューアイテムの発生、トリガーの失敗、プロセスの更新などがあった場合にユーザーに通知することもできます。

Webhook では、さまざまな種類の Orchestrator イベントを外部システムがサブスクライブしてリッスンすることができます。[Webhooks] ページでは、サブスクライブするイベントを簡単に設定でき、作成済みのものを確認することもできます。また、Webhook の無効化、検索、編集、削除も行えます。

イベントは、ジョブ、ロボット、キュー、キューアイテム、プロセス、トリガーで利用可能です。全種類のイベントといくつかの例については、このページで確認してください。

各イベントは、情報を含む指定した URL にペイロードを送信します。プロパティには、すべてに共通なものとイベントの種類に固有のものがあります。

共通のペイロードプロパティ

プロパティ名	プロパティの種類	説明および例
入力	string	通知をトリガーするイベントの種類です。このプロパティはすべてのイベントの種類で表示されます。例： `"Type": "job.created"` `"Type":"process.updated"`
EventId	string	イベント発生時に、イベントに対して一意に生成される ID です。このプロパティはすべてのイベントの種類で表示されます。例： `"EventId":"3e5af0113e674ae597c579cb35ed8630"`
Timestamp	RFC 8601 日付	イベントが生成された日付と時刻です。このプロパティはすべてのイベントの種類で表示されます。例： `"Timestamp":"2018-11-02T11:47:48.5790797Z"`
TenantId	integer	イベントが生成されたテナントの ID です。既定のテナントは 1 です。このプロパティはすべてのイベントの種類で表示されます。例： `"TenantId":3`
UserId	integer	イベントをトリガーしたアクションを実行したユーザーの ID です。イベントが、ロボットまたはトリガーのいずれかによってトリガーされた場合、このパラメーターは表示されません。このプロパティはすべてのイベントの種類で表示されます。例： `"UserId": 4947`
FolderId	integer	イベントが生成されたフォルダーの ID です。イベントがモダンロボットによってトリガーされた場合、このパラメーターは表示されません。例： `"FolderId": 26`

権限

[Webhooks] ページでさまざまな操作を行うには、Webhook 上で該当する権限を持っていなければなりません。

表示 - Webhook とその詳細を確認するとともに、そうした情報を API を使用して取得する、Ping 要求を送信する、Webhook がサブスクライブできる全イベントのリストを取得する、といった操作が可能です。
作成 - この権限があると、新しい Webhook を追加できます。これには、[表示] 権限も必要になります。
編集 - UI または API を使用して Webhook を編集する権限が付与されます。これには、[表示] 権限も必要になります。
削除 - Webhook を削除できる権限です。これには、[表示] 権限も必要になります。

認証

すべての Webhook HTTP 要求は、Webhook の作成時に追加した秘密を使って認証します。これは、HMAC-SHA256 鍵付きハッシュを使用して要求本文と結合されます。その結果、秘密情報を一切含まないセキュリティで保護された署名となります。この署名は、要求ごとに一意であり、X-UiPath-Signature HTTP ヘッダーを通じて送信されます。

Orchestrator の要求を受信するクライアントアプリケーションは、要求の信頼性をチェックする必要があります。要求の署名は、次のパターンに従って行われます。

クライアントアプリケーションは、Orchestrator からの要求を受信します。
クライアントアプリケーションは、要求に基づいて署名を計算します。
クライアントアプリケーションは、自身が計算した署名と要求の署名を照合します。
- 署名が一致しない場合、クライアントアプリケーションは要求を処理しません。
- 署名が一致した場合、クライアントアプリケーションは要求を処理します。

署名の計算は、次のように行われます。

X-UiPath-Signature HTTP ヘッダーを取得します。
署名のローバイトを取得するには、Base64 からヘッダーの値をデコードします。
生の (ロー) 要求本文を取得します。

注: Orchestrator の要求は常に UTF-8 でエンコードされています。
SHA256 と (UTF-8 でエンコードされた) 署名鍵を使用してハッシュを計算します。
計算した署名と X-UiPath-Signature HTTP ヘッダーからの値を照合します。
- 署名が一致しない場合、要求を処理してはいけません。
- 署名が一致した場合、クライアントアプリケーションは要求を処理します。

署名検証の例

using System;
using System.Net.Http;
using System.Security.Cryptography;
using System.Text;
using System.Threading.Tasks;
 
 
public async Task<bool> IsValidRequestAsync(HttpRequestMessage request, string secret)
{
    if (!request.Headers.TryGetValues("X-UiPath-Signature", out var headerValues))
        return false;
 
    var orchestratorSignature = Convert.FromBase64String(headerValues.First());
    using (var sha = new HMACSHA256(key: Encoding.UTF8.GetBytes(secret)))
    {
        var computedSignature = sha.ComputeHash(await request.Content.ReadAsByteArrayAsync());
        return ByteArrayEquals(orchestratorSignature, computedSignature);
    }
}using System;
using System.Net.Http;
using System.Security.Cryptography;
using System.Text;
using System.Threading.Tasks;
 
 
public async Task<bool> IsValidRequestAsync(HttpRequestMessage request, string secret)
{
    if (!request.Headers.TryGetValues("X-UiPath-Signature", out var headerValues))
        return false;
 
    var orchestratorSignature = Convert.FromBase64String(headerValues.First());
    using (var sha = new HMACSHA256(key: Encoding.UTF8.GetBytes(secret)))
    {
        var computedSignature = sha.ComputeHash(await request.Content.ReadAsByteArrayAsync());
        return ByteArrayEquals(orchestratorSignature, computedSignature);
    }
}

const { createServer } = require('http');
const { createHmac } = require('crypto');
 
const PORT = 9090
const WEBHOOK_SECRET = '<same secret as configured in Orchestrator>'
 
const isValidRequest = (body /* Buffer */, secret /* string */, expectedSignature /* string */) =>
    expectedSignature == null || createHmac('sha256', secret)
        .update(body)
        .digest('base64') === expectedSignature
 
const server = createServer((req, resp) => {
 
    let body = new Buffer([])
 
    req.on('data', chunk => body = Buffer.concat([body, chunk]))
 
    req.on('end', () => {
 
        if (!isValidRequest(body, WEBHOOK_SECRET, req.headers['x-uipath-signature'])) {
            console.error('Invalid signature')
            resp.statusCode = 401 // Unauthorized
        } else {
 
            let payload = JSON.parse(body.toString('utf8'))
 
            // Process request
            console.log(payload)
 
            resp.statusCode = 202 // Accepted
        }
 
        resp.end()
    })
 
})
 
server.listen(PORT)const { createServer } = require('http');
const { createHmac } = require('crypto');
 
const PORT = 9090
const WEBHOOK_SECRET = '<same secret as configured in Orchestrator>'
 
const isValidRequest = (body /* Buffer */, secret /* string */, expectedSignature /* string */) =>
    expectedSignature == null || createHmac('sha256', secret)
        .update(body)
        .digest('base64') === expectedSignature
 
const server = createServer((req, resp) => {
 
    let body = new Buffer([])
 
    req.on('data', chunk => body = Buffer.concat([body, chunk]))
 
    req.on('end', () => {
 
        if (!isValidRequest(body, WEBHOOK_SECRET, req.headers['x-uipath-signature'])) {
            console.error('Invalid signature')
            resp.statusCode = 401 // Unauthorized
        } else {
 
            let payload = JSON.parse(body.toString('utf8'))
 
            // Process request
            console.log(payload)
 
            resp.statusCode = 202 // Accepted
        }
 
        resp.end()
    })
 
})
 
server.listen(PORT)