Webhook

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

Webhooks allow external systems to subscribe and listen to different types of Orchestrator events. The Webhooks page enables you to easily set them up, as well as view the ones that have been previously created. You can also disable webhooks, search for a specific one, edit or delete them.

Events are available for jobs, robots, queues, queue items, processes, and triggers. For the full list of event types and a few examples, please check this page.

各イベントは、情報を含む指定した 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 上で該当する権限を持っていなければなりません。

• View - Enables you to view webhooks and their details, as well as retrieve them using the API, send a ping request, or get the list of all the events to which a webhook can subscribe.
• 作成 - この権限があると、新しい Webhook を追加できます。これには、[表示] 権限も必要になります。
• Edit - Grants you the right to edit webhooks from the UI or by using the API. Please note that you also require View permissions.
• 削除 - Webhook を削除できる権限です。これには、[表示] 権限も必要になります。

認証

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

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

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

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

1. X-UiPath-Signature HTTP ヘッダーを取得します。

2. 署名のローバイトを取得するには、Base64 からヘッダーの値をデコードします。

3. 生の (ロー) 要求本文を取得します。

   注:

   Orchestrator の要求は常に UTF-8 でエンコードされています。

4. SHA256 と (UTF-8 でエンコードされた) 署名鍵を使用してハッシュを計算します。

5. 計算した署名と 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);
    }
}

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)