Webhook オートメーションの作成

This feature requires a Pro or Enterprise plan.

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

ハイレベルな手順として、webhook オートメーションを作成するには以下のステップを踏みます：

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

​

webhook を作成する

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

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

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

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

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

4. webhook のエンドポイント URL を入力します。

5. webhook が Bearer トークンを必要とする場合は、Access token をそのトークンを含む secret に設定します。webhook オートメーションを使用すると、W&B は Authorization: Bearer HTTP ヘッダーにアクセストークンを設定し、${ACCESS_TOKEN} ペイロード変数 でトークンにアクセスできます。W&B が webhook サービスに送信する POST リクエストの構造の詳細については、webhook のトラブルシューティング を参照してください。

6. webhook がペイロード内でパスワードやその他の機密文字列を必要とする場合は、Secret をその文字列を含む secret に設定します。その webhook を使用するオートメーションを設定する際、名前の前に $ を付けることで、その secret に ペイロード変数 としてアクセスできます。

   webhook のアクセストークンが secret に保存されている場合は、次のステップも完了して secret をアクセストークンとして指定する必要があります。

7. W&B がエンドポイントに接続し、認証できることを確認します：

   1. オプションで、テスト用のペイロードを提供します。ペイロード内で webhook がアクセス権を持つ secret を参照するには、その名前の前に $ を付けます。このペイロードはテスト目的でのみ使用され、保存されません。オートメーションのペイロードは、オートメーションを作成 する際に設定します。POST リクエスト内で secret とアクセストークンがどこに指定されているかについては、webhook のトラブルシューティング を参照してください。
   2. Test をクリックします。W&B は、設定した資格情報を使用して webhook のエンドポイントへの接続を試みます。ペイロードが提供されている場合、W&B はそれを送信します。

   テストが成功しない場合は、webhook の設定を確認して再試行してください。必要に応じて、webhook のトラブルシューティング を参照してください。

これで、その webhook を使用する オートメーションを作成 できるようになりました。

​

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

webhook を設定 した後、Registry または Project を選択し、以下の手順に従って webhook をトリガーするオートメーションを作成します。

Registry

Registry の管理者は、そのレジストリ内にオートメーションを作成できます。Registry のオートメーションは、将来追加されるものも含め、レジストリ内のすべてのコレクションに適用されます。

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

2. レジストリ名をクリックして詳細を表示します。

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

4. 監視する event を選択します。

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

   Next step をクリックします。

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

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

7. webhook にアクセストークンを設定した場合、${ACCESS_TOKEN} ペイロード変数 でそのトークンにアクセスできます。webhook に secret を設定した場合、名前の前に $ を付けることでペイロード内でその secret にアクセスできます。webhook の要件は、webhook のサービスによって決定されます。

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

9. オートメーションの名前を入力します。オプションで説明を入力します。Create automation をクリックします。

Project

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

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

2. サイドバーで Automations をクリックし、Create automation をクリックします。

   または、ワークスペースのラインプロットから、表示されているメトリクスに対する run metric automation を素早く作成できます。パネルの上にカーソルを置き、パネル上部のベルアイコンをクリックします。

   

3. アーティファクトのエイリアスが追加されたときや、run のメトリクスが特定の閾値に達したときなど、監視する event を選択します。

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

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

         • Filter to one user’s runs: 指定したユーザーによって作成された run のみに限定します。トグルをクリックしてフィルターをオンにし、ユーザー名を指定します。
         • Filter on run name: 名前が指定した正規表現に一致する run のみに限定します。トグルをクリックしてフィルターをオンにし、正規表現を指定します。

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

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

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

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

6. webhook がペイロードを必要とする場合は、ペイロードを作成して Payload フィールドに貼り付けます。webhook にアクセストークンを設定した場合、${ACCESS_TOKEN} ペイロード変数 でそのトークンにアクセスできます。webhook に secret を設定した場合、名前の前に $ を付けることでペイロード内でその secret にアクセスできます。webhook の要件は、webhook のサービスによって決定されます。

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

8. オートメーションの名前を入力します。オプションで説明を入力します。Create automation をクリックします。

​

オートメーションの表示と管理

Registry

レジストリの Automations タブから、レジストリのオートメーションを管理します。

• オートメーションの詳細を表示するには、その名前をクリックします。
• オートメーションを編集するには、アクションメニュー（...）をクリックし、Edit automation をクリックします。
• オートメーションを削除するには、アクションメニュー（...）をクリックし、Delete automation をクリックします。確認が必要です。

Project

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

• オートメーションの詳細を表示するには、その名前をクリックします。
• オートメーションを編集するには、アクションメニュー（...）をクリックし、Edit automation をクリックします。
• オートメーションを削除するには、アクションメニュー（...）をクリックし、Delete automation をクリックします。確認が必要です。

​

ペイロードリファレンス

これらのセクションを使用して、webhook のペイロードを作成してください。webhook とそのペイロードのテストに関する詳細は、webhook のトラブルシューティング を参照してください。

​

ペイロード変数

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

変数	詳細
${project_name}	アクションをトリガーした変更を所有するプロジェクトの名前。
${entity_name}	アクションをトリガーした変更を所有する Entity またはチームの名前。
${event_type}	アクションをトリガーしたイベントのタイプ。
${event_author}	アクションをトリガーしたユーザー。
${alias}	オートメーションが An artifact alias is added イベントによってトリガーされた場合、Artifacts のエイリアスが含まれます。それ以外のオートメーションでは、この変数は空白になります。
${tag}	オートメーションが An artifact tag is added イベントによってトリガーされた場合、Artifacts のタグが含まれます。それ以外のオートメーションでは、この変数は空白になります。
${artifact_collection_name}	アーティファクトバージョンがリンクされているアーティファクトコレクションの名前。
${artifact_metadata.<KEY>}	アクションをトリガーしたアーティファクトバージョンからの任意のトップレベルメタデータキーの値。 <KEY> をトップレベルメタデータキーの名前に置き換えてください。webhook のペイロードでは、トップレベルのメタデータキーのみが使用可能です。
${artifact_version}	アクションをトリガーしたアーティファクトバージョンの Wandb.Artifact 表現。
${artifact_version_string}	アクションをトリガーしたアーティファクトバージョンの string 表現。
${ACCESS_TOKEN}	webhook で設定されている場合、アクセストークンの値。アクセストークンは自動的に 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 ワークフローファイルがあるとします：

on:
repository_dispatch:
  types: BUILD_AND_DEPLOY

リポジトリのペイロードは以下のようになります：

{
  "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 ペイロードの event_type キーは、GitHub ワークフローの YAML ファイル内の types フィールドと一致する必要があります。

レンダリングされたテンプレート文字列の内容と配置は、オートメーションが設定されているイベントまたはモデルバージョンによって異なります。 ${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 を通じて Registered Models のアーティファクトを利用できます。

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

• モデルの評価とデプロイのためのオートメーション作成ガイドである、動画 Webhook Automations for Model Evaluation および Webhook Automations for Model Deployment をご覧ください。

• Model CI に GitHub Actions の webhook オートメーションを使用する方法を示した W&B レポート を確認してください。Modal Labs の webhook を使用してモデル CI を作成する方法については、こちらの GitHub リポジトリ をチェックしてください。

Microsoft Teams notification

このペイロードの例は、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
  }
]
}

（上記の Teams の例のように）実行時にテンプレート文字列を使用して、W&B のデータをペイロードに挿入できます。

Slack notifications

このセクションは歴史的な経緯のために提供されています。現在 Slack との統合に webhook を使用している場合、W&B は設定を更新して代わりに 新しい Slack インテグレーション を使用することを推奨します。

Slack API ドキュメント に記載されている手順に従って、Slack アプリをセットアップし、incoming webhook インテグレーションを追加してください。 Bot User OAuth Token の下に指定された secret が、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 を編集する際にトラブルシューティングを行うことができます。

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

W&B App UI

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

1. W&B の Team Settings ページに移動します。
2. Webhooks セクションまでスクロールします。
3. webhook 名の横にある横三点リーダー（ミートボールアイコン）をクリックします。
4. Test を選択します。
5. 表示される UI パネルから、表示されたフィールドに POST リクエストを貼り付けます。
   
6. Test webhook をクリックします。W&B App UI 内に、エンドポイントからのレスポンスが投稿されます。
   

デモンストレーションについては、動画 Testing Webhooks in W&B をご覧ください。

Bash script

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

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

• ACCESS_TOKEN
• SECRET
• PAYLOAD
• API_ENDPOINT

webhook_test.sh

#!/bin/bash

# アクセストークンと secret
ACCESS_TOKEN="your_api_key"
SECRET="your_api_secret"

# 送信したいデータ（例：JSON形式）
PAYLOAD='{"key1": "value1", "key2": "value2"}'

# HMAC署名を生成
# セキュリティのため、Wandbはペイロードとwebhookに関連付けられた
# 共有シークレットキーから、HMAC SHA-256アルゴリズムを使用して計算された
# X-Wandb-Signatureをヘッダーに含めます。
SIGNATURE=$(echo -n "$PAYLOAD" | openssl dgst \
-sha256 -hmac "$SECRET" -binary | base64)

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