웹훅 자동화 만들기

W&B에서 특정 이벤트가 발생하면 외부 서비스에 HTTP 요청을 보내는 웹훅 자동화를 생성합니다.

이 기능을 사용하려면 Pro 또는 Enterprise 플랜이 필요합니다.

이 페이지에서는 웹훅 자동화을 만드는 방법을 설명합니다. Slack 자동화를 만들려면 Create a Slack automation을 참고하세요.

웹훅 자동화를 만들려면 대략 다음 단계를 따릅니다.

1. 필요한 경우 자동화에 필요한 각 민감한 문자열(예: 액세스 토큰, 비밀번호, SSH 키)마다 W&B 시크릿을 생성합니다. 시크릿은 Team Settings에서 정의합니다.
2. 웹훅을 생성하여 엔드포인트와 인증 세부 정보를 정의하고, 인테그레이션에 필요한 시크릿에 대한 access 권한을 부여합니다.
3. 자동화를 생성하여 감시할 이벤트와 W&B가 전송할 페이로드를 정의합니다. 페이로드에 필요한 시크릿에 대한 access 권한을 자동화에 부여합니다.

​

웹훅 만들기

팀 관리자는 팀에 웹훅을 추가할 수 있습니다.

웹훅에 Bearer 토큰이 필요하거나 페이로드에 민감한 문자열이 필요한 경우, 웹훅을 만들기 전에 해당 값을 포함하는 시크릿을 생성하세요. 웹훅마다 액세스 토큰은 최대 1개, 그 외 시크릿은 최대 1개까지 설정할 수 있습니다. 웹훅의 인증 및 권한 부여 요구 사항은 웹훅 서비스에 따라 결정됩니다.

1. W&B에 로그인한 다음 Team Settings 페이지로 이동합니다.

2. Webhooks 섹션에서 New webhook을 클릭합니다.

3. 웹훅 이름을 입력합니다.

4. 웹훅의 엔드포인트 URL을 입력합니다.

5. 웹훅에 Bearer 토큰이 필요한 경우, Access token을 해당 값을 포함하는 시크릿으로 설정합니다. 웹훅 자동화를 사용할 때 W&B는 Authorization: Bearer HTTP 헤더에 액세스 토큰을 설정하며, ${ACCESS_TOKEN} 페이로드 변수에서 해당 토큰에 액세스할 수 있습니다. W&B가 웹훅 서비스로 보내는 POST 요청의 구조에 대한 자세한 내용은 Troubleshoot your webhook을 참조하세요.

6. 웹훅 페이로드에 비밀번호나 기타 민감한 문자열이 필요한 경우, Secret을 해당 값을 포함하는 시크릿으로 설정합니다. 웹훅을 사용하는 자동화를 설정할 때는 시크릿 이름 앞에 $를 붙여 페이로드 변수로 액세스할 수 있습니다.

   웹훅의 액세스 토큰이 시크릿에 저장되어 있다면, 해당 시크릿을 액세스 토큰으로 지정하기 위해 반드시 다음 단계도 완료해야 합니다.

7. W&B가 엔드포인트에 연결하고 인증할 수 있는지 확인하려면:

   1. 필요하다면 테스트할 페이로드를 입력합니다. 페이로드에서 웹훅이 액세스할 수 있는 시크릿을 참조하려면 이름 앞에 $를 붙입니다. 이 페이로드는 테스트에만 사용되며 저장되지 않습니다. 자동화의 페이로드는 자동화를 만들 때 설정합니다. 시크릿과 액세스 토큰이 POST 요청의 어디에 지정되는지 보려면 Troubleshoot your webhook을 참조하세요.
   2. Test를 클릭합니다. W&B는 설정한 자격 증명을 사용해 웹훅 엔드포인트에 연결을 시도합니다. 페이로드를 입력한 경우 W&B가 이를 전송합니다.

   테스트에 실패하면 웹훅 설정을 확인한 후 다시 시도하세요. 필요한 경우 Troubleshoot your webhook을 참고하세요.

이제 웹훅을 사용하는 자동화를 만들 수 있습니다.

​

자동화 생성

웹훅을 구성한 후 레지스트리 또는 프로젝트를 선택한 다음, 아래 단계에 따라 웹훅을 트리거하는 자동화를 생성하세요.

레지스트리

레지스트리 관리자는 해당 레지스트리에서 자동화를 생성할 수 있습니다. 레지스트리 자동화는 나중에 추가되는 항목을 포함해 레지스트리의 모든 collection에 적용됩니다.

1. W&B에 로그인합니다.

2. 레지스트리 이름을 클릭해 세부 정보를 확인합니다.

3. 레지스트리 범위의 자동화를 생성하려면 Automations 탭을 클릭한 다음 Create automation을 클릭합니다.

4. 감시할 이벤트를 선택합니다.

   표시되는 추가 필드를 입력합니다. 예를 들어 An artifact alias is added를 선택한 경우 Alias regex를 지정해야 합니다.

   Next step을 클릭합니다.

5. 웹훅을 소유한 팀을 선택합니다.

6. Action type을 Webhooks로 설정한 다음, 사용할 웹훅을 선택합니다.

7. 웹훅용 액세스 토큰을 구성한 경우 ${ACCESS_TOKEN} 페이로드 변수에서 해당 토큰에 액세스할 수 있습니다. 웹훅용 시크릿을 구성한 경우 이름 앞에 $를 붙여 페이로드에서 액세스할 수 있습니다. 웹훅의 requirements는 웹훅 서비스에 따라 달라집니다.

8. Next step을 클릭합니다.

9. 자동화 이름을 입력합니다. 필요하면 설명도 입력합니다. Create automation을 클릭합니다.

프로젝트

W&B 관리자는 프로젝트에서 자동화를 생성할 수 있습니다.

1. W&B에 로그인한 다음 프로젝트 페이지로 이동합니다.

2. 프로젝트 사이드바에서 Automations를 클릭한 다음 Create automation을 클릭합니다.

   또는 Workspace의 선형 플롯에서 해당 플롯에 표시된 metric에 대한 run metric 자동화를 빠르게 생성할 수 있습니다. 패널 위에 마우스를 올린 다음 패널 상단의 종 아이콘을 클릭합니다.

   

3. artifact alias가 추가되거나 run metric이 지정된 임곗값에 도달하는 경우처럼, 감시할 이벤트를 선택합니다.

   1. 이벤트에 따라 표시되는 추가 필드를 입력합니다. 예를 들어 An artifact alias is added를 선택한 경우 Alias regex를 지정해야 합니다.

      1. run에 의해 트리거되는 자동화의 경우, 필요에 따라 하나 이상의 run 필터를 지정합니다.

         • 한 사용자의 run으로 필터링: 지정한 사용자가 생성한 run만 포함합니다. 표시/숨기기를 클릭해 필터를 켠 다음 사용자 이름을 지정합니다.
         • run 이름으로 필터링: 이름이 지정한 정규식과 일치하는 run만 포함합니다. 표시/숨기기를 클릭해 필터를 켠 다음 정규식을 지정합니다.

      이 자동화는 나중에 추가되는 항목을 포함해 프로젝트의 모든 collection에 적용됩니다.

   2. Next step을 클릭합니다.

4. 웹훅을 소유한 팀을 선택합니다.

5. Action type을 Webhooks로 설정한 다음, 사용할 웹훅을 선택합니다.

6. 웹훅에 페이로드가 필요한 경우 페이로드를 구성해 Payload 필드에 붙여넣습니다. 웹훅용 액세스 토큰을 구성한 경우 ${ACCESS_TOKEN} 페이로드 변수에서 해당 토큰에 액세스할 수 있습니다. 웹훅용 시크릿을 구성한 경우 이름 앞에 $를 붙여 페이로드에서 액세스할 수 있습니다. 웹훅의 requirements는 웹훅 서비스에 따라 달라집니다.

7. Next step을 클릭합니다.

8. 자동화 이름을 입력합니다. 필요하면 설명도 입력합니다. Create automation을 클릭합니다.

​

자동화 조회 및 관리

레지스트리

레지스트리의 Automations 탭에서 레지스트리 자동화를 관리합니다.

• 자동화의 세부 정보를 보려면 해당 이름을 클릭합니다.
• 자동화를 편집하려면 해당 자동화의 액션 () 메뉴를 클릭한 다음 자동화 편집을 클릭합니다.
• 자동화를 삭제하려면 해당 자동화의 액션 () 메뉴를 클릭한 다음 자동화 삭제를 클릭합니다. 확인이 필요합니다.

프로젝트

W&B 관리자는 프로젝트의 Automations 탭에서 프로젝트 자동화를 조회하고 관리할 수 있습니다.

• 자동화의 세부 정보를 보려면 해당 이름을 클릭합니다.
• 자동화를 편집하려면 해당 자동화의 액션 () 메뉴를 클릭한 다음 자동화 편집을 클릭합니다.
• 자동화를 삭제하려면 해당 자동화의 액션 () 메뉴를 클릭한 다음 자동화 삭제를 클릭합니다. 확인이 필요합니다.

​

페이로드 레퍼런스

다음 섹션을 사용해 웹훅 페이로드를 구성하세요. 웹훅과 그 페이로드를 테스트하는 방법에 대한 자세한 내용은 Troubleshoot your webhook을 참고하세요.

​

페이로드 변수

이 섹션에서는 웹훅 페이로드를 구성할 때 사용할 수 있는 변수를 설명합니다.

변수	세부 정보
${project_name}	작업을 트리거한 변경을 소유한 프로젝트의 이름입니다.
${entity_name}	작업을 트리거한 변경을 소유한 entity 또는 팀의 이름입니다.
${event_type}	작업을 트리거한 이벤트의 유형입니다.
${event_author}	작업을 트리거한 사용자입니다.
${alias}	자동화가 An artifact alias is added 이벤트로 트리거된 경우 artifact의 alias를 포함합니다. 다른 자동화에서는 이 변수가 비어 있습니다.
${tag}	자동화가 An artifact tag is added 이벤트로 트리거된 경우 artifact의 태그를 포함합니다. 다른 자동화에서는 이 변수가 비어 있습니다.
${artifact_collection_name}	artifact 버전이 연결된 artifact collection의 이름입니다.
${artifact_metadata.<KEY>}	작업을 트리거한 artifact 버전의 임의의 최상위 메타데이터 키 값을 나타냅니다. <KEY>를 최상위 메타데이터 키 이름으로 바꾸세요. 웹훅 페이로드에서는 최상위 메타데이터 키만 사용할 수 있습니다.
${artifact_version}	작업을 트리거한 artifact 버전의 Wandb.Artifact 표현입니다.
${artifact_version_string}	작업을 트리거한 artifact 버전의 string 표현입니다.
${ACCESS_TOKEN}	액세스 토큰이 구성된 경우, 웹훅에 구성된 액세스 토큰의 값입니다. 액세스 토큰은 Authorization: Bearer HTTP 헤더로 자동 전달됩니다.
${SECRET_NAME}	구성된 경우, 웹훅에 구성된 시크릿의 값입니다. SECRET_NAME을 시크릿 이름으로 바꾸세요.

​

페이로드 예시

이 섹션에는 일반적인 몇 가지 사용 사례에 대한 웹훅 페이로드 예시가 포함되어 있습니다. 이 예시는 페이로드 변수를 사용하는 방법을 보여줍니다.

GitHub 저장소 디스패치

액세스 토큰에 GHA 워크플로를 트리거하는 데 필요한 권한이 설정되어 있는지 확인하세요. 자세한 내용은 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}"
    }
}

웹훅 페이로드의 event_type 키는 GitHub 워크플로 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를 통해 등록된 모델 artifact를 사용할 수 있습니다.

• repository dispatch에 대한 자세한 내용은 GitHub Marketplace의 공식 문서를 참조하세요.

• 모델 평가 및 배포를 위한 automation을 만드는 방법을 안내하는 비디오 Webhook Automations for Model Evaluation 및 Webhook Automations for Model Deployment를 시청하세요.

• Model CI에 GitHub Actions 웹훅 automation을 사용하는 방법을 보여 주는 W&B 리포트를 살펴보세요. Modal Labs 웹훅으로 모델 CI를 만드는 방법을 알아보려면 이 GitHub 저장소를 확인하세요.

Microsoft Teams 알림

이 예제 페이로드는 웹훅을 사용해 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 알림

이 섹션은 이전 방식에 대한 참고용입니다. 현재 Slack과 통합하기 위해 웹훅을 사용 중이라면, W&B에서는 대신 새 Slack 인테그레이션을 사용하도록 설정을 업데이트할 것을 권장합니다.

Slack API 문서에 나와 있는 안내에 따라 Slack 앱을 설정하고 수신 웹훅 인테그레이션을 추가하세요. W&B 웹훅의 access token에는 Bot User OAuth Token 아래에 지정된 secret을 사용해야 합니다.

다음은 payload 예시입니다:

{
    "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}"
        }
        }
    ]
}

​

웹훅 문제 해결

W&B App UI를 사용해 대화형으로, 또는 Bash 스크립트를 사용해 프로그래밍 방식으로 웹훅 문제를 해결할 수 있습니다. 새 웹훅을 만들거나 기존 웹훅을 편집할 때 웹훅을 점검할 수 있습니다.

W&B가 POST 요청에 사용하는 형식에 대한 자세한 내용은 Bash 스크립트 탭을 참고하세요.

W&B App UI

팀 관리자는 W&B App UI에서 대화형으로 웹훅을 테스트할 수 있습니다.

1. W&B Team Settings 페이지로 이동합니다.
2. Webhooks 섹션으로 스크롤합니다.
3. 웹훅 이름 옆의 액션 () 메뉴를 클릭합니다.
4. Test를 선택합니다.
5. 표시되는 UI 패널의 해당 필드에 POST 요청을 붙여넣습니다.
   
6. Test webhook을 클릭합니다. 그러면 W&B App UI에 엔드포인트의 응답이 표시됩니다.
   

시연은 Testing Webhooks in W&B 비디오를 참고하세요.

Bash 스크립트

이 셸 스크립트는 웹훅 자동화가 트리거될 때 W&B가 보내는 요청과 유사한 POST 요청을 생성하는 한 가지 방법을 보여줍니다.

아래 코드를 셸 스크립트에 복사해 붙여넣어 웹훅 문제를 해결하세요. 다음 값은 직접 지정하세요.

• ACCESS_TOKEN
• SECRET
• PAYLOAD
• API_ENDPOINT

webhook_test.sh

#!/bin/bash

# 액세스 토큰과 시크릿
ACCESS_TOKEN="your_api_key"
SECRET="your_api_secret"

# 웹훅 엔드포인트의 URL
API_ENDPOINT="https://your.webhook.endpoint/path"

# 전송할 데이터(예: JSON 형식)
PAYLOAD='{"key1": "value1", "key2": "value2"}'

# HMAC 서명을 생성합니다. 보안을 위해 W&B는
# SHA-256을 사용하는 HMAC으로 웹훅과 연결된
# 공유 시크릿 및 페이로드로부터 계산된 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"