Webhook

Gateway는 외부 트리거를 위한 작은 HTTP webhook 엔드포인트를 노출할 수 있습니다.

활성화

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks"
  }
}

참고사항:

  • hooks.enabled=true일 때 hooks.token은 필수입니다.
  • hooks.path는 기본적으로 /hooks입니다.

인증

모든 요청은 hook 토큰을 포함해야 합니다. 헤더를 선호하세요:

  • Authorization: Bearer <token> (권장)
  • x-openclaw-token: <token>
  • ?token=<token> (지원 중단; 경고를 로그하며 향후 주요 릴리스에서 제거될 예정)

엔드포인트

POST /hooks/wake

페이로드:

{ "text": "System line", "mode": "now" }
  • text 필수 (string): 이벤트 설명 (예: "New email received").
  • mode 선택 사항 (now | next-heartbeat): 즉시 heartbeat를 트리거할지 (기본값 now) 또는 다음 주기적 확인을 기다릴지.

효과:

  • Main session에 대한 시스템 이벤트를 대기열에 추가
  • mode=now이면 즉시 heartbeat 트리거

POST /hooks/agent

페이로드:

{
  "message": "Run this",
  "name": "Email",
  "sessionKey": "hook:email:msg-123",
  "wakeMode": "now",
  "deliver": true,
  "channel": "last",
  "to": "+15551234567",
  "model": "openai/gpt-5.2-mini",
  "thinking": "low",
  "timeoutSeconds": 120
}
  • message 필수 (string): Agent가 처리할 프롬프트 또는 메시지.
  • name 선택 사항 (string): Hook의 사람이 읽을 수 있는 이름 (예: "GitHub"), 세션 요약에서 접두사로 사용됨.
  • sessionKey 선택 사항 (string): Agent의 세션을 식별하는 데 사용되는 키. 기본값은 무작위 hook:<uuid>입니다. 일관된 키를 사용하면 hook 컨텍스트 내에서 다회 대화가 가능합니다.
  • wakeMode 선택 사항 (now | next-heartbeat): 즉시 heartbeat를 트리거할지 (기본값 now) 또는 다음 주기적 확인을 기다릴지.
  • deliver 선택 사항 (boolean): true이면 agent의 응답이 메시징 채널로 전송됩니다. 기본값은 true입니다. Heartbeat 확인만 있는 응답은 자동으로 건너뜁니다.
  • channel 선택 사항 (string): 전달을 위한 메시징 채널. 다음 중 하나: last, whatsapp, telegram, discord, slack, mattermost (plugin), signal, imessage, msteams. 기본값은 last입니다.
  • to 선택 사항 (string): 채널의 수신자 식별자 (예: WhatsApp/Signal의 전화번호, Telegram의 채팅 ID, Discord/Slack/Mattermost (plugin)의 채널 ID, MS Teams의 대화 ID). 기본값은 main session의 마지막 수신자입니다.
  • model 선택 사항 (string): 모델 오버라이드 (예: anthropic/claude-3-5-sonnet 또는 별칭). 제한된 경우 허용된 모델 목록에 있어야 합니다.
  • thinking 선택 사항 (string): Thinking 레벨 오버라이드 (예: low, medium, high).
  • timeoutSeconds 선택 사항 (number): Agent 실행의 최대 지속 시간 (초).

효과:

  • Isolated agent 턴 실행 (자체 세션 키)
  • 항상 main session에 요약을 게시
  • wakeMode=now이면 즉시 heartbeat 트리거

POST /hooks/<name> (매핑됨)

커스텀 hook 이름은 hooks.mappings를 통해 해결됩니다 (구성 참조). 매핑은 선택적 템플릿 또는 코드 변환과 함께 임의의 페이로드를 wake 또는 agent 액션으로 변환할 수 있습니다.

매핑 옵션 (요약):

  • hooks.presets: ["gmail"]은 내장 Gmail 매핑을 활성화합니다.
  • hooks.mappings를 사용하면 구성에서 match, action, 템플릿을 정의할 수 있습니다.
  • hooks.transformsDir + transform.module은 커스텀 로직을 위해 JS/TS 모듈을 로드합니다.
  • match.source를 사용하여 일반 수집 엔드포인트를 유지합니다 (페이로드 기반 라우팅).
  • TS 변환은 TS 로더 (예: bun 또는 tsx)가 필요하거나 런타임에 미리 컴파일된 .js가 필요합니다.
  • 매핑에서 deliver: true + channel/to를 설정하여 응답을 채팅 표면으로 라우팅합니다 (channel은 기본적으로 last이며 WhatsApp으로 대체됨).
  • allowUnsafeExternalContent: true는 해당 hook에 대한 외부 콘텐츠 안전 래퍼를 비활성화합니다 (위험; 신뢰할 수 있는 내부 소스에만 해당).
  • openclaw webhooks gmail setup은 openclaw webhooks gmail run을 위한 hooks.gmail 구성을 작성합니다. 전체 Gmail watch 플로우는 Gmail Pub/Sub를 참조하세요.

응답

  • /hooks/wake의 경우 200
  • /hooks/agent의 경우 202 (비동기 실행 시작)
  • 인증 실패 시 401
  • 잘못된 페이로드 시 400
  • 너무 큰 페이로드 시 413

예제

curl -X POST http://127.0.0.1:18789/hooks/wake \
  -H 'Authorization: Bearer SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"text":"New email received","mode":"now"}'

curl -X POST http://127.0.0.1:18789/hooks/agent \
  -H 'x-openclaw-token: SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"message":"Summarize inbox","name":"Email","wakeMode":"next-heartbeat"}'

다른 모델 사용

Agent 페이로드 (또는 매핑)에 model을 추가하여 해당 실행의 모델을 오버라이드하세요:

curl -X POST http://127.0.0.1:18789/hooks/agent \
  -H 'x-openclaw-token: SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"message":"Summarize inbox","name":"Email","model":"openai/gpt-5.2-mini"}'

agents.defaults.models를 적용하는 경우 오버라이드 모델이 거기에 포함되어 있는지 확인하세요.

curl -X POST http://127.0.0.1:18789/hooks/gmail \
  -H 'Authorization: Bearer SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"source":"gmail","messages":[{"from":"Ada","subject":"Hello","snippet":"Hi"}]}'

보안

  • Hook 엔드포인트를 루프백, tailnet 또는 신뢰할 수 있는 리버스 프록시 뒤에 두세요.
  • 전용 hook 토큰을 사용하세요; gateway 인증 토큰을 재사용하지 마세요.
  • Webhook 로그에 민감한 원시 페이로드를 포함하지 마세요.
  • Hook 페이로드는 신뢰할 수 없는 것으로 처리되며 기본적으로 안전 경계로 래핑됩니다. 특정 hook에 대해 이를 비활성화해야 하는 경우 해당 hook의 매핑에서 allowUnsafeExternalContent: true를 설정하세요 (위험).
← 문서로 돌아가기