webhook オートメーションを作成する

特定のイベントが発生したときに外部サービスへ HTTP リクエストを送信する webhook オートメーションを、W&B で作成します。

この機能の利用には、Pro または Enterprise プランが必要です。

このページでは、webhook オートメーションを作成する方法を説明します。Slack オートメーション を作成する場合は、代わりにSlack オートメーション を作成するを参照してください。

webhook オートメーション の作成手順は、大まかに次のとおりです。

1. 必要に応じて、オートメーション で必要となるアクセストークン、パスワード、SSH キーなどの機密文字列ごとに、W&B secret を作成します。Secrets は Team Settings で定義します。
2. webhook を作成して、Endpoint と認可の詳細を定義し、インテグレーションに必要な secret への access を付与します。
3. オートメーション を作成して、監視するeventと、W&B が送信する ペイロード を定義します。ペイロード に必要な secret への access を オートメーション に付与します.

​

Webhook を作成する

チーム管理者 は、チームに webhook を追加できます。

webhook に Bearer token が必要な場合、またはペイロードに機密文字列を含める必要がある場合は、webhook を作成する前にそれを含むシークレットを作成してください。1 つの webhook には、最大 1 つの access token と、その他のシークレット 1 つを設定できます。webhook の認証および認可の要件は、webhook サービスによって決まります。

1. W&B にログインし、Team Settings ページに移動します。

2. Webhooks セクションで、New webhook をクリックします。

3. webhook の名を入力します。

4. webhook の Endpoint URL を入力します。

5. webhook に Bearer token が必要な場合は、Access token にそれを含むシークレットを設定します。webhook オートメーション を使用すると、W&B は Authorization: Bearer HTTP ヘッダーに access token を設定し、${ACCESS_TOKEN} ペイロード variableでその token を参照できます。W&B が webhook サービスに送信する POST リクエストの構造について詳しくは、Troubleshoot your webhook を参照してください。

6. webhook のペイロードにパスワードやその他の機密文字列が必要な場合は、Secret にそれを含むシークレットを設定します。webhook を使用する オートメーション を設定するときは、そのシークレットの名の先頭に $ を付けることで、ペイロード variableとして参照できます。

   webhook の access token がシークレットに保存されている場合は、そのシークレットを access token として指定するため、_必ず_次の step も完了してください。

7. W&B が endpoint に接続し、認証できることを Verify するには:

   1. 必要に応じて、テスト用のペイロードを入力します。ペイロード内で webhook がアクセスできるシークレットを参照するには、その名の先頭に $ を付けます。このペイロードはテストにのみ使用され、保存されません。オートメーション のペイロードは、オートメーション を作成するときに設定します。シークレットと access token が POST リクエスト内のどこで指定されるかは、Troubleshoot your webhook を参照してください。
   2. Test をクリックします。W&B は、設定した認証情報を使用して webhook の endpoint への接続を試みます。ペイロードを入力した場合、W&B はそれを送信します。

   テストが成功しない場合は、webhook の設定を確認して再試行してください。必要に応じて、Troubleshoot your webhook を参照してください。

これで、webhook を使用するオートメーション を作成できます。

​

オートメーション を作成する

webhook を設定したら、Registry または プロジェクト を選択し、webhook をトリガーする オートメーション を作成するには、次の step に従います。

Registry

Registry 管理者は、その Registry で オートメーション を作成できます。Registry オートメーション は、今後追加されるものも含め、Registry 内のすべての collection に適用されます。

1. W&B にログインします。

2. Registry の詳細を表示するには、Registry の名をクリックします。

3. Registry をスコープとする オートメーション を作成するには、Automations タブをクリックし、Create automation をクリックします。

4. 監視するイベントを選択します。

   表示される追加フィールドに入力します。たとえば、An artifact alias is added を選択した場合は、Alias regex を指定する必要があります。

   Next step をクリックします。

5. webhookを所有するチームを選択します。

6. Action type を Webhooks に設定し、使用する webhook を選択します。

7. webhook に access token を設定した場合は、ペイロード 変数 ${ACCESS_TOKEN} でその token を参照できます。webhook に secret を設定した場合は、その名の先頭に $ を付けることで ペイロード 内で参照できます。webhook の requirements は、webhook のサービスによって決まります。

8. Next step をクリックします。

9. オートメーション の名を指定します。必要に応じて説明も指定します。Create automation をクリックします。

Project

W&B 管理者は、プロジェクトで オートメーション を作成できます。

1. W&B にログインし、プロジェクト ページに移動します。

2. プロジェクトのサイドバーで Automations をクリックし、Create automation をクリックします。

   または、Workspace の折れ線グラフから、そのグラフに表示されているメトリクスに対する run メトリクス オートメーション をすばやく作成できます。パネルにカーソルを合わせ、パネル上部のベル アイコンをクリックします。

   

3. 監視するイベントを選択します。たとえば、artifact alias が追加されたときや、run メトリクスが指定したしきい値に達したときです。

   1. 表示される追加フィールドに入力します。これらはイベントによって異なります。たとえば、An artifact alias is added を選択した場合は、Alias regex を指定する必要があります。

      1. run によってトリガーされる オートメーション では、必要に応じて 1 つ以上の run フィルターを指定します。

         • 1 人のユーザーの Runs にフィルターする: 指定したユーザーが作成した Runs のみを含めます。toggle をクリックしてフィルターをオンにし、ユーザー名を指定します。
         • run 名でフィルターする: 名が指定した正規表現に一致する Runs のみを含めます。toggle をクリックしてフィルターをオンにし、正規表現を指定します。

      この オートメーション は、今後追加されるものも含め、プロジェクト内のすべての collection に適用されます。

   2. Next step をクリックします。

4. webhookを所有するチームを選択します。

5. Action type を Webhooks に設定し、使用する webhook を選択します。

6. webhook に ペイロード が必要な場合は、それを作成して Payload フィールドに貼り付けます。webhook に access token を設定した場合は、ペイロード 変数 ${ACCESS_TOKEN} でその token を参照できます。webhook に secret を設定した場合は、その名の先頭に $ を付けることで ペイロード 内で参照できます。webhook の requirements は、webhook のサービスによって決まります。

7. Next step をクリックします。

8. オートメーション の名を指定します。必要に応じて説明も指定します。Create automation をクリックします。

​

オートメーションを表示および管理する

Registry

Registry の Automations タブから、Registry のオートメーションを管理できます。

• オートメーションの詳細を表示するには、その名をクリックします。
• オートメーションを編集するには、その action () メニューをクリックしてから、Edit automation をクリックします。
• オートメーションを削除するには、その action () メニューをクリックしてから、Delete automation をクリックします。確認が必要です。

プロジェクト

W&B 管理者は、プロジェクトの Automations タブからプロジェクトのオートメーションを表示および管理できます。

• オートメーションの詳細を表示するには、その名をクリックします。
• オートメーションを編集するには、その action () メニューをクリックしてから、Edit automation をクリックします。
• オートメーションを削除するには、その action () メニューをクリックしてから、Delete automation をクリックします。確認が必要です。

​

ペイロード リファレンス

以下のセクションを使用して、webhook のペイロードを作成します。webhook とそのペイロードのテストの詳細については、Troubleshoot your webhookを参照してください。

​

ペイロード変数

このセクションでは、webhook のペイロードの構築に使用できる変数について説明します。

Variable	Details
${project_name}	アクションをトリガーしたミューテーションを所有するプロジェクト名。
${entity_name}	アクションをトリガーしたミューテーションを所有する entity またはチームの名。
${event_type}	アクションをトリガーしたイベントのタイプ。
${event_author}	アクションをトリガーしたユーザー。
${alias}	オートメーションが An artifact alias is added イベントによってトリガーされた場合、artifact の alias が入ります。それ以外のオートメーションでは、この変数は空です。
${tag}	オートメーションが An artifact tag is added イベントによってトリガーされた場合、artifact の tags が入ります。それ以外のオートメーションでは、この変数は空です。
${artifact_collection_name}	artifact バージョンがリンクされている artifact collection の名。
${artifact_metadata.<KEY>}	アクションをトリガーした artifact バージョン内の、任意のトップレベル metadata キーの値です。<KEY> はトップレベル metadata キーの名に置き換えてください。webhook のペイロードで使用できるのは、トップレベル metadata キーのみです。
${artifact_version}	アクションをトリガーした artifact バージョンの Wandb.Artifact 表現。
${artifact_version_string}	アクションをトリガーした artifact バージョンの string 表現。
${ACCESS_TOKEN}	access token が設定されている場合、webhook で設定した access token の値です。access token は Authorization: Bearer HTTP ヘッダーで自動的に渡されます。
${SECRET_NAME}	設定されている場合、webhook で設定した secret の値です。SECRET_NAME は secret の名に置き換えてください。

​

ペイロードの例

このセクションでは、一般的なユースケースにおける webhook のペイロード例をいくつか紹介します。これらの例では、ペイロード変数の使い方を示します。

GitHub repository dispatch

GitHub Actions ワークフローをトリガーするには、アクセストークンに必要な権限が付与されていることを確認してください。詳細については、こちらの GitHub Docs を参照してください。

W&B から repository dispatch を送信して、GitHub Action をトリガーします。たとえば、on キーのトリガーとして repository dispatch を受け取る GitHub workflow ファイルがあるとします。

on:
repository_dispatch:
  types: BUILD_AND_DEPLOY

repository のペイロードは、次のようなものです。

{
  "event_type": "BUILD_AND_DEPLOY",
  "client_payload": 
  {
    "event_author": "${event_author}",
    "artifact_version": "${artifact_version}",
    "artifact_version_string": "${artifact_version_string}",
    "artifact_collection_name": "${artifact_collection_name}",
    "project_name": "${project_name}",
    "entity_name": "${entity_name}"
    }
}

webhook payload の event_type キーは、GitHub workflow の YAML ファイル内にある types フィールドと一致している必要があります。

表示されるテンプレート文字列の内容と配置は、automation が設定されているイベントまたはモデルバージョンによって異なります。${event_type} は LINK_ARTIFACT または ADD_ARTIFACT_ALIAS として表示されます。対応関係の例は以下のとおりです。

${event_type} --> "LINK_ARTIFACT" or "ADD_ARTIFACT_ALIAS"
${event_author} --> "<wandb-user>"
${artifact_version} --> "wandb-artifact://_id/QXJ0aWZhY3Q6NTE3ODg5ODg3""
${artifact_version_string} --> "<entity>/model-registry/<registered_model_name>:<alias>"
${artifact_collection_name} --> "<registered_model_name>"
${project_name} --> "model-registry"
${entity_name} --> "<entity>"

テンプレート文字列を使用して、W&B から GitHub Actions やその他のツールにコンテキストを動的に渡します。これらのツールが Python スクリプトを呼び出せる場合は、W&B API を介して登録済みのモデル Artifacts を利用できます。

• repository dispatch の詳細については、GitHub Marketplace の公式ドキュメントを参照してください。

• Webhook Automations for Model Evaluation と Webhook Automations for Model Deployment の動画をご覧ください。これらの動画では、モデルの評価とデプロイ向けの automation を作成する方法を紹介しています。

• Model CI に GitHub Actions の webhook automation を使用する方法を示した W&B レポートをご確認ください。Modal Labs webhook を使ってモデル CI を作成する方法については、このGitHub repositoryも参照してください。

Microsoft Teams の通知

このペイロード例では、webhook を使用して Teams チャンネルに通知する方法を示します。

{
"@type": "MessageCard",
"@context": "http://schema.org/extensions",
"summary": "New Notification",
"sections": [
  {
    "activityTitle": "Notification from WANDB",
    "text": "This is an example message sent via Teams webhook.",
    "facts": [
      {
        "name": "Author",
        "value": "${event_author}"
      },
      {
        "name": "Event Type",
        "value": "${event_type}"
      }
    ],
    "markdown": true
  }
]
}

テンプレート文字列を使用すると、実行時に W&B データをペイロードへ挿入できます (上記の Teams の例のとおり) 。

Slack 通知

このセクションは、過去の経緯を示す参考情報として掲載しています。現在 webhook を使用して Slack と統合している場合、W&B では、代わりに新しい Slack インテグレーションを使用するよう設定を更新することを推奨しています。

Slack API ドキュメントで案内されている手順に従って Slack アプリを設定し、incoming webhook インテグレーションを追加してください。Bot User OAuth Token に指定されているシークレットを、W&B webhook のアクセストークンとして使用していることを確認してください。

以下はペイロードの例です。

{
    "text": "New alert from WANDB!",
"blocks": [
    {
            "type": "section",
        "text": {
            "type": "mrkdwn",
            "text": "Registry event: ${event_type}"
        }
    },
        {
            "type":"section",
            "text": {
            "type": "mrkdwn",
            "text": "New version: ${artifact_version_string}"
        }
        },
        {
        "type": "divider"
    },
        {
            "type": "section",
        "text": {
            "type": "mrkdwn",
            "text": "Author: ${event_author}"
        }
        }
    ]
}

​

webhook のトラブルシューティング

W&B App UI を使ってインタラクティブに、または Bash スクリプトを使ってプログラムから、webhook をトラブルシューティングできます。新しい webhook を作成するときや既存の webhook を編集するときに、webhook をトラブルシューティングできます。

W&B が POST リクエストに使用する形式の詳細については、Bash スクリプト タブを参照してください。

W&B App UI

チーム管理者は、W&B App UI を使って webhook をインタラクティブにテストできます。

1. W&B の Team Settings ページにアクセスします。
2. Webhooks セクションまでスクロールします。
3. webhook の名前の横にある action () メニューをクリックします。
4. Test を選択します。
5. 表示された UI パネルで、表示されたフィールドに POST リクエストを貼り付けます。
   
6. Test webhook をクリックします。W&B App UI 内に、エンドポイントからのレスポンスが表示されます。
   

デモについては、動画 Testing Webhooks in W&B をご覧ください。

Bash スクリプト

このシェルスクリプトは、webhook オートメーション がトリガーされたときに W&B が送信するリクエストに近い POST リクエストを生成する方法の一例を示しています。

以下のコードをシェルスクリプトにコピー＆ペーストして、webhook をトラブルシューティングしてください。以下の項目には独自の値を指定します。

• ACCESS_TOKEN
• SECRET
• PAYLOAD
• API_ENDPOINT

webhook_test.sh

#!/bin/bash

# access token と secret
ACCESS_TOKEN="your_api_key"
SECRET="your_api_secret"

# webhook エンドポイントの URL
API_ENDPOINT="https://your.webhook.endpoint/path"

# 送信するデータ（たとえば JSON 形式）
PAYLOAD='{"key1": "value1", "key2": "value2"}'

# HMAC 署名を生成します。セキュリティのため、W&B は
# ペイロードと、SHA-256 を使用する HMAC で webhook に関連付けられた
# 共有secretから計算された X-Wandb-Signature ヘッダーを含めます。
SIGNATURE=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')

# cURL リクエストを実行します
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Wandb-Signature: $SIGNATURE" \
  -d "$PAYLOAD" "$API_ENDPOINT"