Webhook 通知のカスタマイズ方法 - Data Management - Alibaba Cloud ドキュメントセンター

Data Management (DMS) では、ショートメッセージ、メール、DingTalk 通知、DingTalk チャットボット通知に加えて、カスタム Webhook URL を通知チャネルとして利用できます。DMS 内でイベントが発生すると、DMS は設定した Webhook URL に対して POST リクエストを送信します。

Webhook URL の設定

DMS コンソールで、通知方法の設定を開きます。
Webhook セクションの Webhook URL フィールドに、ご利用のエンドポイントを入力します。
Webhook を選択して、通知チャネルとして有効化します。

詳細については、「個人情報および通知方法の設定」をご参照ください。

POST リクエストのフォーマット

通知がトリガーされると、DMS は設定済みの Webhook URL に対して POST リクエストを送信します。

リクエストヘッダー

ヘッダー	値	説明
`DMS-Event`	`Message Hook`	このリクエストが DMS の Webhook 通知であることを識別します。

リクエストボディ

パラメーター	型	説明
`submitterUid`	文字列	タスクを提出したアカウントの ID です。
`submitterName`	文字列	タスクを提出したアカウントの名前です。
`category`	文字列	タスクが属するモジュール（例：チケット、タスクオーケストレーション、データウェアハウス開発）です。
`module`	文字列	ビジネスタイプ（例：権限申請、データ変更、スキーマ設計、データエクスポート）です。
`event`	文字列	タスクのステータスによってトリガーされるイベント（例：承認待ち、成功、失敗）です。
`taskId`	文字列	チケットまたはタスクフローの ID です。
`taskName`	String	タスクの名称です。
`eventTime`	String	イベントが発生した時刻です。
`message`	String	DMS から提供される事前定義済みのメッセージです。
`targetUsers`	Array	通知の対象となる 1 名以上の受信者です。各エントリには `uid` と `name` が含まれます。
`receivers`	Array	実際に通知を受信する 1 名以上の受信者です。通知方法を設定していないユーザーは通知を受信しません。各エントリには `uid` と `name` が含まれます。
`signatureMethod`	String	Webhook の署名方式です。有効な値： None（デフォルト、署名なし）、HMAC_SHA1（ハッシュ化メッセージ認証コード・セキュアハッシュアルゴリズム 1）。
`signatureText`	String	Webhook URL、パスワード、メッセージイベントに基づき HMAC_SHA1 で計算されたデジタル署名です。例：`4mOdwflN1CgxxxxxxxuipuCYYWk=`。

サンプルリクエスト

{
  "messageEvent": {
    "submitterName": "xxx",
    "submitterUid": "167382665015xxxx",
    "category": "Tickets",
    "event": "Success",
    "eventTime": 1625630049930,
    "message": "[DMS] Webhook test, code: 144619 ",
    "Module": "Data change",
    "receivers": [{"name": "xxx1", "uid": "167382665015xxxx"}, {"name": "xxx2", "uid": "167382665016xxxx"}],
    "targetUsers": [{"name": "xxx1", "uid": "167382665015xxxx"}, {"name": "xxx2", "uid": "167382665016xxxx"}],
    "taskName": "Webhook test"
  },
  "signatureMethod": "HMAC_SHA1",
  "signatureText": "4mOdwflN1Cg5NdM2XPuipuCYYWk="
}

サンプル応答

成功時：

{"root": "", "success": true}

失敗時：

{"root": "error message", "success": false}

署名の検証

Webhook の設定時に HMAC_SHA1 署名を有効化した場合、サーバー側で署名を再計算し、signatureText と比較することで、着信リクエストの正当性を検証してください。

署名の入力文字列は、以下の連結結果です：webhookUrl + password + JSON.toJSONString(messageEvent)。

// DMS Webhook リクエストからの署名検証
public void callback(String message) {
    JSONObject jsonObject = JSONObject.parseObject(message, Feature.OrderedField);
    String webhookUrl = "Webhook URL";
    String password = "Signature key";
    String origin = webhookUrl + password + JSON.toJSONString(jsonObject.getJSONObject("messageEvent"));

    // DMS リクエストに付与された署名
    String signatureText = jsonObject.getString("signatureText");

    // サーバー側で再計算した署名
    String expectedSignatureText = signatureByHmacSha1(origin, password);
    assert Objects.equals(signatureText, expectedSignatureText);
}

public String signatureByHmacSha1(String origin, String key) {
    final String charset = "UTF-8";
    String result = "N/A";
    try {
        SecretKey secretKey = new SecretKeySpec(key.getBytes(charset), "HmacSHA1");
        Mac mac = Mac.getInstance("HmacSHA1");
        mac.init(secretKey);
        result = Base64.getEncoder().encodeToString(mac.doFinal(origin.getBytes(charset)));
    } catch (Exception ex) {
    }
    return result;
}

署名検証失敗時のトラブルシューティング

ペイロードが DMS 由来であるにもかかわらず署名検証が失敗する場合は、以下の点を確認してください：

署名キー： サーバー側で使用しているパスワードが、DMS で設定した署名キーと一致していることを確認してください。
入力文字列の順序： HMAC_SHA1 の入力は、webhookUrl + password + JSON.toJSONString(messageEvent) — この順序でなければなりません。
JSON シリアル化： messageEvent オブジェクトは、連結前に JSON にシリアル化する必要があります。解析済みオブジェクトを再シリアル化せず、生のリクエストボディ文字列を使用すると、異なる結果になる可能性があります。
文字エンコーディング： 全ての文字列は UTF-8 でエンコードしてください。DMS 側とサーバー側のエンコーディングが不一致の場合、署名の不一致が発生します。
プロキシまたはロードバランサー： サーバーがプロキシやロードバランサーの後ろにある場合、リクエストボディやヘッダーがコードに到達する前に改変されていないか確認してください。

Webhook のテスト

DMS が送信する生の POST リクエストを確認するために、ローカルのエコーサーバーを利用します。

以下のスクリプトを print_http_body.rb として保存します：

require 'webrick'
server = WEBrick::HTTPServer.new(:Port => ARGV.first)
server.mount_proc '/' do |req, res|
  puts req.body
end
trap 'INT' do
  server.shutdown
end
server.start

利用可能なポートでサーバーを起動します：
```
ruby print_http_body.rb 8000
```
DMS コンソールで、http://my.host:8000/ を Webhook URL として設定します。詳細については、「個人情報および通知方法の設定」をご参照ください。新しい DMS コンソール

通知方法の変更 ダイアログボックスで、Webhook URL フィールドの右側にある テスト をクリックします。DMS がテスト通知をエンドポイントに送信します。エコーサーバーがリクエストボディを出力し、以下のような形式になります：

{
  "messageEvent": {
    "submitterName": "xxx",
    "submitterUid": "167382665015xxxx",
    "category": "Tickets",
    "event": "Success",
    "eventTime": 1625630049930,
    "message": "[DMS] Webhook test, code: 144619 ",
    "Module": "Data change",
    "receivers": [{"name": "xxx1", "uid": "167382665015xxxx"}],
    "targetUsers": [{"name": "xxx1", "uid": "167382665015xxxx"}],
    "taskName": "Webhook test"
  },
  "signatureMethod": "HMAC_SHA1",
  "signatureText": "4mOdwflN1Cg5NdM2XPuipuCYYWk="
}
127.0.0.1 - - [20/Apr/2021:20:07:47 CST] "POST / HTTP/1.1" 200 0

サーバーが HTTP Basic 認証を使用している場合、認証情報を Webhook URL に直接含めてください：

http://userName:password@my.host:8080/project/test-job