Webhook 도구

Webhook 도구 (Webhook Tool)

에이전트가 구성한 목적지로 알림을 보내는 방법을 설명해요. Slack, Discord, Telegram, IFTTT 등 다양한 서비스의 webhook 페이로드를 처리해 줘요.

출처: 문서

본문

webhook 도구셋은 사용자가 구성한 목적지로 알림을 전달해요. 에이전트는 메시지 텍스트만 제공해요: URL을 보지도 고르지도 않아요. webhook URL 자체가 자격 증명이기 때문이에요(Slack과 Mattermost는 비밀 경로를, Discord는 토큰을, IFTTT는 키를, Telegram은 봇 토큰을 임베드해요).

이것은 일반 HTTP 클라이언트가 아니에요 — 그건 api 도구셋이에요. webhook 도구셋은 전달을 소유해요:

  • 최소 한 번 전달(at-least-once). 일시적 실패(429, 5xx, 네트워크 오류)는 지수 백오프로 재시도되고, 서버의 Retry-After를 존중해요. 4xx는 영구적이라 재시도를 낭비하지 않고 즉시 실패해요.
  • 비차단. 알림이 큐에 들어가면 호출이 곧바로 반환되므로, 느리거나 재시도하는 엔드포인트가 에이전트의 턴을 막지 않아요. 전달이 결국 실패할 때만 에이전트에게 다시 메시지를 보내요.
  • 폭풍 보호. 짧은 시간 안에 같은 목적지로 동일한 메시지가 나가는 것을 억제하고, 알림이 속도 제한되어서 루프 도는 에이전트가 채널을 범람시킬 수 없어요.
  • 프로바이더 형태 페이로드. 각 서비스의 와이어 형식이 자동으로 적용돼요.

구성

목적지는 webhook_config에 있어요. 비밀스러운 것은 ${env.VAR}를 사용하세요 — 값은 호출 시점에 확장되고 구성 파일에 절대 저장되지 않아요.

toolsets:
  - type: webhook
    webhook_config:
      provider: slack
      url: ${env.SLACK_WEBHOOK_URL}
필드 필수 설명
url 네 webhook 엔드포인트. 보통 비밀을 임베드 — ${env.VAR} 선호
provider 아니오 페이로드 형태(기본 generic)
headers 아니오 토큰으로 인증하는 엔드포인트용 추가 헤더
chat_id 아니오 대상 채팅 — provider: telegram에 필수

도구셋의 timeout(초)은 요청별 HTTP 타임아웃을 덮어써요.

프로바이더

프로바이더 보내는 페이로드 비밀이 있는 곳
slack, mattermost, rocketchat, googlechat, teams, generic {"text": message} 비밀 webhook URL
discord {"content": message} webhook URL의 토큰
ifttt {"value1": message, "value2": …, "value3": …} webhook URL의 키
telegram {"chat_id": …, "text": message} URL의 봇 토큰 + chat_id

별칭이 받아들여져요: msteams/microsoft_teams → teams, google_chat/gchat → googlechat, rocket.chat → rocketchat.

서비스별 예시

# Slack / Mattermost / Rocket.Chat — URL이 자격 증명
toolsets:
  - type: webhook
    webhook_config:
      provider: slack
      url: ${env.SLACK_WEBHOOK_URL}

# Discord — 토큰은 webhook URL의 일부
toolsets:
  - type: webhook
    webhook_config:
      provider: discord
      url: ${env.DISCORD_WEBHOOK_URL}

# Telegram — 봇 토큰은 URL에, chat_id가 대상 채팅 선택
toolsets:
  - type: webhook
    webhook_config:
      provider: telegram
      url: https://api.telegram.org/bot${env.TELEGRAM_BOT_TOKEN}/sendMessage
      chat_id: "123456789"

# IFTTT — 키는 트리거 URL의 일부
toolsets:
  - type: webhook
    webhook_config:
      provider: ifttt
      url: https://maker.ifttt.com/trigger/build_failed/with/key/${env.IFTTT_KEY}

# Bearer 토큰으로 인증하는 일반 엔드포인트
toolsets:
  - type: webhook
    webhook_config:
      provider: generic
      url: https://alerts.example.com/notify
      headers:
        Authorization: Bearer ${env.ALERTS_TOKEN}

send_webhook

파라미터 필수 설명
message 네 전달할 메시지 텍스트
value2, value3 아니오 추가 IFTTT 데이터 필드(provider: ifttt)

큐에 들어가면 즉시 반환돼요. 성공 시 더 일어나는 일은 없고, 전달이 결국 실패하면 에이전트가 그렇게 알리는 메시지를 받아요.

예시

agents:
  root:
    model: openai/gpt-5-mini
    instruction: If a check fails, notify the team with send_webhook.
    toolsets:
      - type: webhook
        webhook_config:
          provider: slack
          url: ${env.SLACK_WEBHOOK_URL}

참고 비공개 주소로의 요청은 거부돼요(SSRF 안전 HTTP 클라이언트), 그리고 구성된 URL은 모델이나 오류 메시지에 절대 다시 보여주지 않아요.

더 알아보기 (Learn more)