webhooks

anchor alias

sidebar_position: 13 title: "웹훅" description: "GitHub, GitLab 및 Hermes 에이전트를 트리거하는 다른 서비스에서 이벤트를 수신"

웹훅

외부 서비스 (GitHub, GitLab, JIRA, Stripe 등)의 이벤트를 수신하고 Hermes 에이전트가 자동으로 실행됩니다. webhook 어댑터는 POST 요청을 수락하는 HTTP 서버를 실행, HMAC 서명을 검증, 에이전트 프롬프트로 페이로드를 변환, 소스 또는 다른 구성 플랫폼에 대한 응답을 경로.

에이전트는 이벤트를 처리하고 PR에 대한 의견을 게시하여 응답 할 수 있으며, 메시지를 Telegram/Discord로 전송하거나 결과를 기록 할 수 있습니다.

비디오 자습서

동영상 보기

빠른 시작

hermes gateway setup 또는 환경 변수를 통해 활성화
config.yaml 또는의 경로 정의는 hermes webhook subscribe로 동적으로 만듭니다.
http://your-server:8644/webhooks/<route-name>에서 당신의 서비스를 점하세요

설치

webhook 어댑터를 활성화하는 두 가지 방법이 있습니다.

설치 마법사를 통해

웹훅을 활성화하고 포트를 설정하고 글로벌 HMAC 비밀을 설정합니다.

환경 변수를 통해

~/.hermes/.env에 추가하세요:

WEBHOOK_ENABLED=true
WEBHOOK_PORT=8644        # default
WEBHOOK_SECRET=your-global-secret

서버 검증

게이트웨이가 실행되면:

예상된 응답:

노선 구성 {#configuring-routes}

Route는 다른 웹훅 소스가 처리되는 방법을 정의합니다. 각 노선은 platforms.webhook.extra.routes에서 config.yaml의 이름을 입력합니다.

노선 속성

재산	필수	묘사
`events`	No	이벤트 유형 일람표 비어 있는 경우, 모든 이벤트가 접수됩니다. 이벤트 유형은 `X-GitHub-Event`, `X-GitLab-Event` 또는 `event_type`에서 payload에 읽습니다. ·
`secret`	Yes	시그니처 검증을 위한 HMAC 비밀 루트에 설정하지 않는 경우 글로벌 `secret`로 다시 폭포. 테스트용 `"INSECURE_NO_AUTH"`로 설정 (스키스 유효성 검사).
`prompt`	No	도트 주석 페이로드 액세스가있는 템플릿 문자열 (예: `{pull_request.title}`). omitted 경우, 전체 JSON 페이로드는 프롬프트로 덤프됩니다.
`skills`	No	대리점에 적재하는 기술명 목록
`deliver`	아니오	응답을 보낼 곳: `github_comment`, `telegram`, `discord`, `slack`, `signal`, `sms`, `whatsapp`, `matrix`, `mattermost`, `homeassistant`, `homeassistant`, ZX5000`whatsapp`, discord``github_comment, github_comment``github_comment, telegram``telegram``telegram``telegram, telegram``discord
`deliver_extra`	No	`deliver` 타입(예: `repo`, `pr_number`, `pr_number`, `chat_id`) `prompt`와 같은 `{dot.notation}` 템플릿을 지원합니다.
`deliver_only`	No	`true`가 전적으로 에이전트를 건너면 렌더링된 `prompt` 템플릿이 전달되는 문학 메시지가 됩니다. Zero LLM 비용, 하위 배송. 사용 사례에 대한 Direct Delivery Mode를 참조하세요. 실제 대상이 될 `deliver`를 요구합니다 (`log`가 아닙니다). ·

전체 예

platforms:
  webhook:
    enabled: true
    extra:
      port: 8644
      secret: "global-fallback-secret"
      routes:
        github-pr:
          events: ["pull_request"]
          secret: "github-webhook-secret"
          prompt: |
            Review this pull request:
            Repository: {repository.full_name}
            PR #{number}: {pull_request.title}
            Author: {pull_request.user.login}
            URL: {pull_request.html_url}
            Diff URL: {pull_request.diff_url}
            Action: {action}
          skills: ["github-code-review"]
          deliver: "github_comment"
          deliver_extra:
            repo: "{repository.full_name}"
            pr_number: "{number}"
        deploy-notify:
          events: ["push"]
          secret: "deploy-secret"
          prompt: "New push to {repository.full_name} branch {ref}: {head_commit.message}"
          deliver: "telegram"

Prompt 템플릿

Prompts는 웹훅 페이로드에서 배열 된 필드에 액세스 할 점 주석을 사용합니다.

{pull_request.title}는 payload["pull_request"]["title"]에 해결
{repository.full_name}는 payload["repository"]["full_name"]에 해결
{__raw__} - **entire 페이로드를 덤프하는 특수 토큰 ** indented JSON (4000 문자에 따라). 에이전트가 전체 컨텍스트를 필요로 하는 경우 경고 또는 일반 webhooks를 모니터링하는 데 유용합니다.
미스 키는 리터 {key} 문자열로 왼쪽 (오류 없음)
Nested dicts and lists는 2000 문자에 JSON 직렬화 및 truncated입니다.

{__raw__}를 일반 템플릿 변수로 섞을 수 있습니다.

prompt: "PR #{pull_request.number} by {pull_request.user.login}: {__raw__}"

prompt 템플릿이 경로에 구성되지 않은 경우 전체 페이로드는 indented JSON으로 덤프됩니다 (4000 문자로 변환).

같은 점 주석 템플릿은 deliver_extra 값에서 작동합니다.

포럼 주제 전달

Telegram에 웹훅 응답을 제공 할 때 message_thread_id (또는 thread_id)를 포함하여 특정 포럼 주제를 대상으로 할 수 있습니다. deliver_extra:

chat_id가 deliver_extra에서 제공되지 않은 경우, 배송은 대상 플랫폼을 위해 구성된 홈 채널로 돌아갑니다.

GitHub PR 검토 (단계별 단계) {#github-pr-review}

이 walkthrough는 각 잡아당기기 요구에 자동적인 부호 검토를 놓습니다.

##1. GitHub에서 webhook 만들기

저장소로 이동 → ** 설정**→** 웹훅 → 웹훅 추가 **
Payload URL를 http://your-server:8644/webhooks/github-pr로 설정
application/json에 내용 유형를 놓으십시오
경로 설정 (예: github-webhook-secret)에 맞게 ** 설정
** 어디 이벤트?**, select 개인 이벤트를 선택 및 체크패럴 요청
클릭 **웹훅 추가 **

##2. 경로 설정 추가

github-pr 노선을 ~/.hermes/config.yaml로 추가하세요.

##3. gh CLI 인증

github_comment 배송 유형은 GitHub CLI를 사용하여 댓글을 게시합니다.

4. 그것을 시험하세요

저장소에 pull request를 엽니다. webhook fires, Hermes는 이벤트를 처리하고, PR에 대한 검토 의견을 게시합니다.

GitLab Webhook 설정 {#gitlab-webhook-setup}

GitLab webhooks는 비슷하지만 다른 인증 메커니즘을 사용합니다. GitLab은 일반 X-Gitlab-Token 헤더로 비밀을 보냅니다 (문자 일치, HMAC가 아닌).

##1. GitLab에서 webhook 만들기

프로젝트로 이동 → ** 설정**→** 웹훅 **
URL를 http://your-server:8644/webhooks/gitlab-mr로 설정
토큰을 입력
선택 **Merge 요청 이벤트 ** (그리고 원하는 다른 이벤트)
클릭 **웹훅 추가 **

##2. 경로 설정 추가

platforms:
  webhook:
    enabled: true
    extra:
      routes:
        gitlab-mr:
          events: ["merge_request"]
          secret: "your-gitlab-secret-token"
          prompt: |
            Review this merge request:
            Project: {project.path_with_namespace}
            MR !{object_attributes.iid}: {object_attributes.title}
            Author: {object_attributes.last_commit.author.name}
            URL: {object_attributes.url}
            Action: {object_attributes.action}
          deliver: "log"

납품 선택권 {#delivery-options}

deliver 필드 제어 에이전트의 응답은 webhook 이벤트를 처리 한 후 간다.

유형 전달	설명
`log`	게이트웨이 로그 출력에 대한 응답을 기록합니다. 이것은 기본적으로이며 테스트에 유용합니다. ·
`github_comment`	`gh` CLI를 통해 PR/issue 주석으로 응답합니다. `deliver_extra.repo` 및 `deliver_extra.pr_number`가 필요합니다. `gh` CLI는 게이트웨이 호스트 (`gh auth login`)에 설치 및 인증해야합니다. ·
`telegram`	텔레그램에 대한 응답을 경로. 홈 채널을 사용하거나 `chat_id`를 `deliver_extra`에 지정하세요. ·
`discord`	Discord에 대한 응답을 추적합니다. 홈 채널을 사용하거나 `chat_id`를 `deliver_extra`에 지정하세요. ·
`slack`	Slack에 대한 응답을 경로. 홈 채널을 사용하거나 `chat_id`를 `deliver_extra`에 지정하세요. ·
`signal`	시그널에 대응하는 노선 홈 채널을 사용하거나 `chat_id`를 `deliver_extra`에 지정하세요. ·
`sms`	Twilio를 통해 SMS로 응답합니다. 홈 채널을 사용하거나 `chat_id`를 `deliver_extra`에 지정하세요. ·
`whatsapp`	WhatsApp에 대응 홈 채널을 사용하거나 `chat_id`를 `deliver_extra`에 지정하세요. ·
`matrix`	매트릭스에 대응하는 루트 홈 채널을 사용하거나 `chat_id`를 `deliver_extra`에 지정하세요. ·
`mattermost`	Mattermost 대응 홈 채널을 사용하거나 `chat_id`를 `deliver_extra`에 지정하세요. ·
`homeassistant`	Home Assistant에 대한 응답을 경로. 홈 채널을 사용하거나 `chat_id`를 `deliver_extra`에 지정하세요. ·
`email`	이메일 대응 홈 채널을 사용하거나 `chat_id`를 `deliver_extra`에 지정하세요. ·
`dingtalk`	DingTalk에 대한 응답을 추적합니다. 홈 채널을 사용하거나 `chat_id`를 `deliver_extra`에 지정하세요. ·
`feishu`	Feishu/Lark의 대응 경로. 홈 채널을 사용하거나 `chat_id`를 `deliver_extra`에 지정하세요. ·
`wecom`	WeCom에 대한 응답을 경로. 홈 채널을 사용하거나 `chat_id`를 `deliver_extra`에 지정하세요. ·
`weixin`	Weixin (WeChat)에 대한 응답을 추적합니다. 홈 채널을 사용하거나 `chat_id`를 `deliver_extra`에 지정하세요. ·
`bluebubbles`	BlueBubbles (iMessage)에 대한 응답을 경로. 홈 채널을 사용하거나 `chat_id`를 `deliver_extra`에 지정하세요. ·

cross-platform 납품을 위해, 표적 플랫폼은 또한 게이트웨이에서 활성화되고 연결되어야 합니다. chat_id가 deliver_extra에서 제공되지 않은 경우 해당 플랫폼의 구성 홈 채널에 응답이 전송됩니다.

직접 배달 모드 {#direct-delivery-mode}

기본적으로, 모든 webhook POST 트리거 에이전트 실행 — 페이로드는 프롬프트가되고, 에이전트는 그것을 처리하고, 에이전트의 응답이 전달됩니다. 모든 이벤트에서 LLM 토큰이 발생합니다.

를 위해 사용할 경우push a Plain notification — no reasoning, no Agent loop, just deliver message — set deliver_only: true on the route. 렌더링 된 prompt 템플릿은 리터럴 메시지 몸이며, 어댑터는 직접 구성 된 배달 목표에 파견합니다.

직접 배달을 사용할 때

**외부 서비스 푸시 ** - 데이터베이스 변경에 Supabase/Firebase webhook 화재 → 즉시 Telegram에서 사용자를 통지
Monitoring alerts — Datadog/Grafana alert webhook → Discord 채널에 푸시 -Inter-agent pings — Agent A notifies Agent B's user that long-running task 완성
배경 작업 완료 - Cron 작업 완료 → Slack 결과

이점:

**영 LLM 토큰 ** - 에이전트는 결코 잘못되지 않습니다 -Sub-second Delivery — 단일 어댑터 호출, 이유 루프 없음
에이전트 모드로 같은 보안 - HMAC auth, 속도 제한, idempotency 및 신체 크기 제한 여전히 적용
**Synchronous 응답 ** - POST는 200 OK를 한 번 납품 성공, 또는 502를 한 번 반환하여 대상이 그것을 거부 할 경우, 사용자의 업스트림 서비스는 지능적으로 구출 할 수 있습니다

예: Supabase에서 전보 푸시

모델 번호: ```yaml platforms: webhook: enabled: true extra: port: 8644 secret: "global-secret" routes: antenna-matches: secret: "antenna-webhook-secret" deliver: "telegram" deliver_only: true prompt: "🎉 New match: {match.user_name} matched with you!" deliver_extra: chat_id: "{match.telegram_chat_id}"

당신의 Supabase 가장자리 기능은 `https://your-server:8644/webhooks/antenna-matches`에 HMAC-SHA256 및 POSTs를 가진 페이로드를 나타냅니다. webhook 어댑터는 서명을 검증하고 payload에서 템플릿을 렌더링하고 Telegram에 전달하며 `200 OK`를 반환합니다.

### 예제: CLI를 통한 동적 구독

```bash
hermes webhook subscribe antenna-matches \
  --deliver telegram \
  --deliver-chat-id "123456789" \
  --deliver-only \
  --prompt "🎉 New match: &#123;match.user_name&#125; matched with you!" \
  --description "Antenna match notifications"

응답 부호

현황	의미
`200 OK`	성공적으로 배송 바디: `{"status": "delivered", "route": "...", "target": "...", "delivery_id": "..."}`
`200 OK`(status=duplicate)	중복 `X-GitHub-Delivery` idempotency TTL (1 시간) 내의 ID. 다시 배달합니다.
모델 번호: `401 Unauthorized`	HMAC 시그니처 무효 또는 누락.
`400 Bad Request`	변형된 JSON 몸.
`404 Not Found`	알려진 노선명.
`413 Payload Too Large`	몸은 `max_body_bytes`를 초과했습니다.
`429 Too Many Requests`	노선 제한이 초과되었습니다.
`502 Bad Gateway`	대상 어댑터는 메시지나 올리기를 거부합니다. 오류가 로그 서버 측입니다. 응답 몸은 일반적인 `Delivery failed`이며, 어댑터 내부를 누출 방지합니다. ·

윤곽 gotchas

deliver_only: true는 실제 대상이 될 deliver가 필요합니다. deliver: log (또는 deliver를 omitting)는 시작시 거부됩니다. 어댑터는 잘못 구성된 루트를 찾을 경우 시작을 거부합니다.
skills 필드는 직접 배달 모드에서 무시됩니다 (제임이 실행되지 않도록 기술을 주사하는 것은 아무것도 없습니다).
템플릿 렌더링은 {__raw__} 토큰을 포함한 에이전트 모드와 동일한 {dot.notation} 구문을 사용합니다.
Idempotency는 동일한 X-GitHub-Delivery/X-Request-ID 우두머리를 이용합니다 — 동일한 ID 반환 status=duplicate를 가진 화물은 재 납품하지 않습니다.

동적 구독 (CLI)

config.yaml의 정적 경로 외에도 hermes webhook CLI 명령을 사용하여 웹훅 구독을 동적으로 만들 수 있습니다. 에이전트 자체가 이벤트 구동 트리거를 설정해야 할 때 특히 유용합니다.

hermes webhook subscribe github-issues \
  --events "issues" \
  --prompt "New issue #&#123;issue.number&#125;: &#123;issue.title&#125;\nBy: &#123;issue.user.login&#125;\n\n&#123;issue.body&#125;" \
  --deliver telegram \
  --deliver-chat-id "-100123456789" \
  --description "Triage new GitHub issues"

이것은 webhook URL과 자동 생성된 HMAC 비밀을 반환합니다. POST에서 URL로 서비스를 구성합니다.

리스트 구독

hermes webhook list

구독 제거

hermes webhook remove github-issues

구독 테스트

hermes webhook test github-issues
hermes webhook test github-issues --payload '&#123;"issue": &#123;"number": 42, "title": "Test"&#125;&#125;'

동적 구독 작업

구독은 ~/.hermes/webhook_subscriptions.json에 저장됩니다
webhook 어댑터 핫로드 각 수신 요청에 이 파일 (mtime-gated, negligible overhead)
config.yaml의 정적 경로는 항상 동일한 이름을 가진 동적인 그들에 전진합니다
동적 구독은 정적 경로(events, prompt Templates, Skill, Delivery)와 동일한 경로 형식과 기능을 사용합니다.
게이트웨이 재시작 필요 없음 - 가입 및 즉시 라이브

에이전트 구동 구독

에이전트는 webhook-subscriptions 기술에 의해 안내 될 때 터미널 도구를 통해 구독을 만들 수 있습니다. " GitHub 문제의 webhook 설정" 에이전트를 요청하고 적절한 hermes webhook subscribe 명령을 실행합니다.

보안

webhook 어댑터에는 여러 레이어의 보안이 포함되어 있습니다.

HMAC 서명 검증

어댑터는 각 소스에 적합한 방법을 사용하여 웹훅 서명을 검증합니다.

GitHub: X-Hub-Signature-256 헤더 - HMAC-SHA256 hex는 sha256=로 사전 설정
GitLab: X-Gitlab-Token 헤더 - 일반 비밀 문자열 일치 -Generic: X-Webhook-Signature 헤더 - 원시 HMAC-SHA256 hex 소화

비밀이 구성되었지만 인식되지 않은 서명 헤더가 존재하면 요청이 거부됩니다.

비밀 필수

모든 루트는 비밀이 있어야 합니다. 루트에 직접 설정하거나 글로벌 secret에서 상속. 비밀없이 경로는 어댑터가 오류로 시작하지 못합니다. 개발/테스트를 위해서 "INSECURE_NO_AUTH"에 비밀을 설정할 수 있습니다.

INSECURE_NO_AUTH는 게이트웨이가 루프백 호스트 (127.0.0.1, localhost, ::1)에 바인딩 될 때만 허용됩니다. 0.0.0.0 또는 LAN IP와 같은 비 루프 백 묶음과 결합되면 어댑터는 시작을 거부합니다. 이것은 실수로 공공 인터페이스의 무해한 엔드 포인트를 폭발시킵니다.

비율 제한

각 경로는 기본(fixed-window)에 의하여 **30개의 요청으로 제한됩니다. 글로벌 구성:

platforms:
  webhook:
    extra:
      rate_limit: 60  # requests per minute

제한을 초과하는 요청은 429 Too Many Requests 응답을받습니다.

이민

배달 ID (X-GitHub-Delivery, X-Request-ID, 또는 타임스탬프 fallback에서)는 ** 1 시간 동안 캐시됩니다 **. 중복 배송 (예: webhook retries)은 200 응답으로 자동으로 건너 뛰고 중복 에이전트가 실행을 방지합니다.

몸 크기 한계

1 MB를 초과하는 페이로드는 몸 앞에 거부됩니다. 이 구성:

platforms:
  webhook:
    extra:
      max_body_bytes: 2097152  # 2 MB

Prompt 주입 위험

대여

Webhook 페이로드에는 공격자 제어 데이터가 포함되어 있습니다. - PR 타이틀, 커밋 메시지, 문제 설명, 기타. 모든 악의적 인 지침을 포함 할 수 있습니다. 인터넷에 노출 될 때 sandboxed 환경에서 게이트웨이를 실행 (Docker, VM). 도커 또는 SSH 터미널을 사용하여 고립에 대한 백엔드를 고려하십시오. 주요 특징

문제 해결

웹훅 도착하지

포트가 노출되고 webhook 소스에서 접근 가능
방화벽 규칙 확인 - 포트 8644 (또는 설정된 포트)는 열려야 합니다.
URL 경로 일치 검증: http://your-server:8644/webhooks/<route-name>
서버가 실행되도록 /health 엔드포인트를 사용하십시오.

서명 유효성 검사 실패

웹훅 소스에서 설정된 비밀을 정확히 일치합니다.
GitHub의 경우 비밀은 HMAC 기반이며 X-Hub-Signature-256를 확인하십시오.
GitLab의 경우, 비밀은 일반 토큰 일치입니다 - X-Gitlab-Token를 확인
Invalid signature 경고에 대한 게이트웨이 로그 확인

이벤트 무시

해당 이벤트 유형은 경로의 events 목록에 있습니다.
GitHub 이벤트는 pull_request, push, issues (X-GitHub-Event 헤더 값)와 같은 값을 사용합니다.
GitLab 이벤트는 merge_request, push (X-GitLab-Event 헤더 값)와 같은 값을 사용합니다.
events가 비어 있거나 설정되지 않은 경우 모든 이벤트가 허용됩니다.

대리인은 반응하지 않습니다

로그를 볼 수있는 전경의 게이트웨이를 실행: hermes gateway run
신속한 템플릿이 올바르게 렌더링되도록 확인
배송 대상을 지정하고 연결

중복 응답

idempotency 캐시는 이것을 방지해야 합니다 — webhook 근원이 납품 ID 우두머리 (X-GitHub-Delivery 또는 X-Request-ID)를 보내는 검사
배송 ID는 1 시간 동안 캐시됩니다.

`gh` CLI 오류 (GitHub 댓글 전달)

게이트웨이 호스트에 gh auth login 실행
Authenticated GitHub 사용자는 저장소에 대한 액세스를 작성했습니다.
gh가 설치되고 PATH에 확인합니다.

환경 변수

변수	설명	기본
`WEBHOOK_ENABLED`	웹훅 플랫폼 어댑터 사용 가능	`false`
모델 번호: `WEBHOOK_PORT`	웹훅 수신용 HTTP 서버 포트	`8644`
`WEBHOOK_SECRET`	노선이 지정되지 않을 때 글로벌 HMAC 비밀	(none)

anchor alias​

sidebar_position: 13 title: "웹훅" description: "GitHub, GitLab 및 Hermes 에이전트를 트리거하는 다른 서비스에서 이벤트를 수신"​

웹훅

비디오 자습서​

빠른 시작​

설치​

설치 마법사를 통해​

환경 변수를 통해​

서버 검증​

노선 구성 {#configuring-routes}​

노선 속성​

전체 예​

Prompt 템플릿​

포럼 주제 전달​

GitHub PR 검토 (단계별 단계) {#github-pr-review}​

4. 그것을 시험하세요​

GitLab Webhook 설정 {#gitlab-webhook-setup}​

납품 선택권 {#delivery-options}​

직접 배달 모드 {#direct-delivery-mode}​

직접 배달을 사용할 때​

예: Supabase에서 전보 푸시​

응답 부호​

윤곽 gotchas​

동적 구독 (CLI)​

구독하기​

리스트 구독​

구독 제거​

구독 테스트​

동적 구독 작업​

에이전트 구동 구독​

보안​

HMAC 서명 검증​

비밀 필수​

비율 제한​

이민​

몸 크기 한계​

Prompt 주입 위험​

문제 해결​

웹훅 도착하지​

서명 유효성 검사 실패​

이벤트 무시​

대리인은 반응하지 않습니다​

중복 응답​

gh CLI 오류 (GitHub 댓글 전달)​

환경 변수​