Webhooks — 유니버설 이벤트 입구 | Easy Understand Hermes Agent

Webhooks — 유니버설 이벤트 입구

이런 상황을 상상해 보세요. 개발자가 GitHub에서 풀 리퀘스트를 열면, 몇 초 안에 AI 에이전트가 코드를 검토하고 댓글을 달아줍니다. 또는 Stripe에서 결제가 실패하면, 에이전트가 자동으로 팀에 Telegram으로 알림을 보냅니다. 이것이 바로 webhooks의 마법입니다 — 외부 서비스가 에이전트의 문을 두드리며 “야, 방금 뭔가 일어났어, 처리해줘”라고 말하는 거죠.

Webhooks란 무엇인가?

Webhooks는 애플리케이션의 초인종과 같습니다. 무언가 변경되었는지 계속 확인하는 방식(폴링) 대신, 그냥 초인종이 울리기를 기다리면 됩니다. GitHub, GitLab, JIRA, Stripe 또는 다른 어떤 서비스가 HTTP POST 요청을 webhook 엔드포인트로 보내면, Hermes 에이전트가 깨어나 이벤트를 처리하고 행동을 취합니다.

가장 좋은 점은? 에이전트가 다양한 방식으로 응답할 수 있다는 것입니다 — PR에 댓글 달기, Telegram이나 Discord로 메시지 보내기, 또는 나중에 검토할 수 있도록 결과를 로그로 남기기까지.

빠른 시작

시작하는 방법은 놀라울 정도로 간단합니다:

hermes gateway setup 또는 환경 변수를 통해 webhook 어댑터를 활성화합니다
config.yaml에서 라우트를 정의하거나 hermes webhook subscribe로 동적으로 생성합니다
서비스를 http://your-server:8644/webhooks/<route-name>으로 연결합니다

끝입니다. 이제 에이전트가 대기 상태가 된 겁니다.

게이트웨이 설정하기

Webhooks를 활성화하는 방법은 두 가지입니다. 편한 쪽을 선택하세요.

옵션 1: 설정 마법사

hermes gateway setup

안내에 따라 webhooks를 활성화하고, 포트를 선택하고, 글로벌 HMAC 시크릿을 설정하세요. 마법사가 지루한 설정을 모두 처리해 줍니다.

옵션 2: 환경 변수

~/.hermes/.env에 다음 줄을 추가하세요:

WEBHOOK_ENABLED=true
WEBHOOK_PORT=8644        # 기본값
WEBHOOK_SECRET=your-global-secret

게이트웨이가 실행되면, 정상 동작을 확인해 보세요:

curl http://localhost:8644/health

다음과 같은 응답이 표시됩니다:

{"status": "ok", "platform": "webhook"}

라우트 구성하기

라우트는 webhook 처리의 핵심입니다. 각 라우트는 특정 소스의 이벤트를 에이전트가 어떻게 처리할지 알려줍니다. 서로 다른 유형의 방문객을 위한 맞춤형 지침이라고 생각하면 됩니다.

라우트별로 설정할 수 있는 항목은 다음과 같습니다:

속성	기능
`events`	수락할 이벤트 유형 (예: `["pull_request"]`). 비워두면 모든 것을 수락합니다.
`secret`	서명 검증을 위한 HMAC 시크릿. 테스트용으로만 `"INSECURE_NO_AUTH"`를 사용하세요.
`profile`	이 라우트를 실행할 수 있는 프로필 (멀티플렉싱에 유용).
`prompt`	`{pull_request.title}` 같은 점 표기법을 사용하는 템플릿 문자열. 생략하면 전체 JSON 페이로드를 출력합니다.
`filters`	에이전트가 실행되기 전에 원치 않는 페이로드를 무시하는 선언적 조건.
`script`	템플릿 적용 전에 페이로드를 수정할 수 있는 필터/변환 스크립트.
`skills`	이 에이전트 실행에 로드할 스킬.
`toolsets`	에이전트가 사용할 수 있는 도구 (기본 webhook 도구셋을 대체).
`deliver`	응답을 보낼 위치: `github_comment`, `telegram`, `discord`, `slack`, `log` 등.
`deliver_extra`	저장소 이름이나 채팅 ID 같은 추가 전달 세부 정보.
`deliver_only`	에이전트를 완전히 건너뛰고 렌더링된 프롬프트를 그대로 전달. LLM 비용 제로!

실제 예제

실용적인 설정을 살펴보겠습니다. 풀 리퀘스트를 검토하는 라우트입니다:

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

그리고 누군가 메인 브랜치에 푸시할 때만 Telegram 알림을 보내는 라우트입니다:

        deploy-notify:
          events: ["push"]
          secret: "deploy-secret"
          prompt: "New push to {repository.full_name} branch {ref}: {head_commit.message}"
          filters:
            - field: "ref"
              equals: "refs/heads/main"
          deliver: "telegram"

스마트 필터링

filters 기능은 특히 유용합니다. 제공업체는 종종 이벤트를 쏟아내지만, 실제로 관심 있는 것은 몇 개뿐입니다. 필터를 사용하면 에이전트가 깨어나기 전에 노이즈를 무시할 수 있습니다. 조건에 맞지 않는 페이로드에는 HTTP 200과 함께 정중한 {"status":"ignored","reason":"filter"} 응답이 반환됩니다 — 낭비되는 컴퓨팅도, 불필요한 LLM 호출도 없습니다.

직접 전달 모드

여기 영리한 트릭이 있습니다: deliver_only: true를 설정하면 에이전트가 전혀 실행되지 않습니다. 렌더링된 프롬프트 템플릿이 그대로 전달되는 메시지가 됩니다. 즉, LLM 비용 제로로 1초 미만의 전달이 가능합니다. AI 추론이 필요 없는 단순 알림에 완벽합니다.

보안 참고 사항

기억하세요: 인증되었다고 해서 신뢰할 수 있는 것은 아닙니다. Webhook의 페이로드 필드는 신뢰할 수 없는 데이터입니다. 프롬프트나 템플릿에서 사용하는 모든 것은 항상 검증하고 정화하세요. 에이전트는 webhook 콘텐츠를 사용자 입력처럼 취급해야 합니다 — 건강한 회의감을 가지고요.

결론

Webhooks는 Hermes 에이전트를 실시간으로 세상에 반응하는 즉각 대응형 어시스턴트로 바꿔줍니다. 코드 리뷰 자동화, 배포 알림 전송, 복잡한 이벤트 기반 워크플로우 구축까지, webhook 어댑터는 몇 줄의 YAML만으로 모든 것을 가능하게 합니다.