LangSmith 알림을 위한 webhook 알림 구성하기

​

개요

​

사전 요구 사항

• HTTP POST 요청을 수신할 수 있는 endpoint
• 수신 서비스에 대한 적절한 인증 자격 증명 (필요한 경우)

​

통합 구성

​

1단계: 수신 Endpoint 준비하기

• HTTP POST 요청을 수락함
• JSON payload를 처리할 수 있음
• 외부 서비스에서 액세스 가능함
• 적절한 인증 메커니즘이 있음 (필요한 경우)

​

2단계: Webhook 매개변수 구성하기

• URL: 수신 endpoint의 전체 URL
  • 예시: https://api.example.com/incident-webhook

• Headers: webhook 요청과 함께 전송되는 JSON Key-value 쌍
  • 일반적인 header는 다음과 같습니다:
    • Authorization: 인증 token용
    • Content-Type: 일반적으로 application/json로 설정 (기본값)
    • X-Source: 소스를 LangSmith로 식별하기 위해
  • header가 없는 경우 단순히 {}를 사용하세요
• Request Body Template: endpoint로 전송되는 JSON payload를 사용자 정의
  • 기본값: LangSmith는 정의된 payload와 다음 추가 key-value 쌍을 payload에 추가하여 전송합니다:
    • project_name: 트리거된 알림의 이름
    • alert_rule_id: LangSmith 알림을 식별하는 UUID. webhook 서비스에서 중복 제거 키로 사용할 수 있습니다.
    • alert_rule_name: 알림 규칙의 이름.
    • alert_rule_type: 알림 유형 (2025년 4월 1일 기준 모든 알림은 threshold 유형입니다).
    • alert_rule_attribute: 알림 규칙과 연결된 속성 - error_count, feedback_score 또는 latency.
    • triggered_metric_value: 임계값이 트리거된 시점의 메트릭 값.
    • triggered_threshold: 알림을 트리거한 임계값.
    • timestamp: 알림을 트리거한 타임스탬프.

​

3단계: Webhook 테스트하기

​

문제 해결

• webhook URL이 올바르고 액세스 가능한지 확인하세요
• 인증 header가 올바르게 형식화되었는지 확인하세요
• 수신 endpoint가 POST 요청을 수락하는지 확인하세요
• 수신되었지만 거부된 요청에 대해 endpoint의 로그를 검토하세요
• 사용자 정의 payload template이 유효한 JSON 형식인지 확인하세요

​

보안 고려 사항

• webhook endpoint에 HTTPS를 사용하세요
• webhook endpoint에 대한 인증을 구현하세요
• webhook 소스를 확인하기 위해 header에 공유 비밀을 추가하는 것을 고려하세요
• 처리하기 전에 들어오는 webhook 요청을 검증하세요

​

Webhook을 사용하여 Slack으로 알림 보내기

​

사전 요구 사항

• Slack workspace에 대한 액세스
• 알림을 설정할 LangSmith project
• Slack application을 생성할 수 있는 권한

​

1단계: Slack App 생성하기

1. Slack API Applications 페이지 방문
2. Create New App 클릭
3. From scratch 선택
4. App Name 제공 (예: “LangSmith Alerts”)
5. 앱을 설치할 workspace 선택
6. Create App 클릭

​

2단계: Bot 권한 구성하기

1. Slack 앱 구성의 왼쪽 사이드바에서 OAuth & Permissions 클릭
2. Scopes 아래의 Bot Token Scopes로 스크롤하여 Add an OAuth Scope 클릭
3. 다음 scope를 추가하세요:
   • chat:write (앱으로 메시지 전송)
   • chat:write.public (앱이 속하지 않은 채널에 메시지 전송)
   • channels:read (기본 채널 정보 보기)

​

3단계: Workspace에 앱 설치하기

1. OAuth & Permissions 페이지 상단으로 스크롤
2. Install to Workspace 클릭
3. 권한을 검토하고 Allow 클릭
4. 표시되는 Bot User OAuth Token 복사 (xoxb-로 시작)

​

4단계: LangSmith에서 Webhook 알림 구성하기

1. LangSmith에서 project로 이동
2. Alerts → Create Alert 선택
3. 알림 메트릭 및 조건 정의
4. 알림 섹션에서 Webhook 선택
5. 다음 설정으로 webhook 구성:

https://slack.com/api/chat.postMessage

{
  "Content-Type": "application/json",
  "Authorization": "Bearer xoxb-your-token-here"
}

참고: xoxb-your-token-here를 실제 Bot User OAuth Token으로 교체하세요

{
  "channel": "{channel_id}",
  "text": "{alert_name} triggered for {project_name}",
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "🚨{alert_name} has been triggered"
      }
    },
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "Please check the following link for more information:"
      }
    },
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "<{project-url}|View in LangSmith>"
      }
    }
  ]
}

6. Save를 클릭하여 webhook 구성을 활성화하세요

​

5단계: 통합 테스트하기

1. LangSmith 알림 구성에서 Test Alert 클릭
2. 지정된 Slack 채널에서 테스트 알림 확인
3. 메시지에 예상된 알림 정보가 포함되어 있는지 확인

​

(선택 사항) 6단계: Request Body에 알림 미리보기 링크 추가하기

1. 알림 저장
2. 알림 테이블에서 저장된 알림을 찾아 클릭
3. 표시된 URL 복사
4. “Edit Alert” 클릭
5. 기존 project URL을 복사한 알림 미리보기 URL로 교체

​

추가 리소스

• LangSmith Alerts 문서
• Slack chat.postMessage API 문서
• Slack Block Kit Builder