Skip to main content

Webhooks

HTTP를 통해 외부 시스템에서 에이전트 작업을 트리거하거나 에이전트 결과를 외부 서비스로 푸시합니다.

인바운드 트리거

외부 시스템(Zapier, n8n, 사용자 정의 스크립트)은 Cron 트리거 엔드포인트에 HTTP 요청을 보내 에이전트 작업을 트리거할 수 있습니다.

Webhook 트리거

이벤트 트리거

시스템 이벤트 트리거

아웃바운드 Webhooks

Webhook 채널을 사용하여 설정 > 채널에서 아웃바운드 웹후크를 구성합니다. 에이전트 결과는 구조화된 JSON POST 요청으로 구성된 URL에 자동으로 푸시됩니다.

보안

인바운드

인바운드 웹후크 트리거에는 Cron 작업에 구성된 비밀과 일치해야 하는 x-webhook-secret 헤더가 필요합니다. 유효한 비밀번호가 없는 요청은 401로 거부됩니다.

아웃바운드

모든 아웃바운드 웹훅 요청은 여러 보안 계층으로 보호됩니다.
  • SSRF 보호: 모든 아웃바운드 HTTP 요청은 DNS 고정 및 개인 네트워크 차단을 통해 secure_request()을 통과합니다. Webhook 내부 IP(127.0.0.1, 10.x, 192.168.x 등)를 가리키는 URL은 자동으로 거부됩니다.
  • HMAC-SHA256 서명: 아웃바운드 웹후크 페이로드에는 수신자가 요청 신뢰성을 확인할 수 있는 X-Webhook-Signature 헤더(sha256=...)가 포함됩니다. 가장 강력한 확인을 위해 웹훅별로 비밀을 구성하세요.
  • 리디렉션 검증: 아웃바운드 요청은 홉별 SSRF 검증을 통해 리디렉션을 따릅니다. 내부 주소로의 리디렉션은 원래 URL이 공개인 경우에도 차단됩니다.
  • Fire-and-Forget 모드: 알림 유형 후크(예: SessionEnd)는 Fire-and-forget으로 구성될 수 있습니다. HTTP 호출은 기본 에이전트 흐름을 차단하지 않고 비동기식으로 실행되며 세션을 중단하지 않고 실패가 기록됩니다.

GitHub 통합

내장된 GitHub 채널은 PR 검토, 문제 관리 및 푸시 이벤트 처리를 위한 기본 웹훅 통합을 제공합니다.
  1. 설정 > 통합 > GitHub으로 이동합니다.
  2. 개인 액세스 토큰(PAT)을 입력하세요.
  3. Webhook 비밀 구성
  4. GitHub 이벤트(PR 열림, 문제, 푸시)가 전체 컨텍스트와 함께 에이전트 응답을 자동으로 트리거합니다.
HMAC-SHA256 서명 확인은 실제 GitHub 페이로드만 처리되도록 보장합니다. 셀프 서비스 웹훅 URL: GitHub 설정 카드에 웹훅 URL이 복사 버튼과 함께 직접 표시됩니다. GitHub 저장소의 Settings → Webhooks에서 이 URL을 추가할 때 위에서 설정한 것과 동일한 Webhook Secret을 입력해야 합니다. 그렇지 않으면 GitHub의 서명 확인(X-Hub-Signature-256)이 401로 이벤트를 조용히 거부하고 PR 이벤트가 도착하지 않습니다.

GUI을(를) 통해 설정

  1. 설정 > 자동화(Cron)로 이동합니다.
  2. 새로운 예약 작업 생성
  3. 트리거 유형으로 “Webhook”을 선택합니다.
  4. 웹훅 경로 및 비밀 구성
  5. 트리거 시 실행할 에이전트 바인딩

자연어 설정

대화를 통해 웹훅 트리거를 구성할 수도 있습니다.
“결제 시스템에서 들어오는 데이터를 처리하는 웹훅 트리거를 만드는 데 도움을 주세요.”
에이전트는 자동으로 트리거를 설정하고, 웹훅 URL과 비밀을 생성하고, 외부 시스템 구성을 안내합니다.