OpenClaw Webhook 통합 및 이벤트 콜백

서문

실제 프로덕션 환경에서 AI Agent는 보통 독립적으로 실행되지 않으며, 기업의 기존 시스템과 양방향으로 통합해야 합니다. OpenClaw은 완전한 Webhook 메커니즘을 제공하여, 특정 이벤트가 발생했을 때 외부 시스템에 콜백 알림을 보내거나, 외부 시스템에서 이벤트를 수신하여 Agent 동작을 트리거할 수 있습니다.

이 글에서는 OpenClaw의 Webhook 통합 방안을 전반적으로 소개하여, 이벤트 기반 AI 워크플로를 구축하는 데 도움을 드립니다.

Webhook 기본 개념

OpenClaw의 Webhook 시스템은 두 가지 방향으로 나뉩니다:

아웃바운드 Webhook(Outgoing): OpenClaw 내부에서 특정 이벤트가 발생했을 때, 설정한 URL로 HTTP POST 요청을 전송합니다
인바운드 Webhook(Incoming): 외부 시스템이 HTTP 요청을 통해 OpenClaw의 Agent 작업 실행을 트리거합니다

아웃바운드 흐름:
  OpenClaw 이벤트 → HTTP POST → 사용자 서버

인바운드 흐름:
  사용자 서버 → HTTP POST → OpenClaw → Agent 처리 → 콜백 알림

아웃바운드 Webhook 설정

기본 설정

openclaw.json5에 Webhook 설정을 추가합니다:

{
  webhooks: {
    endpoints: [
      {
        // Webhook 이름
        name: "main-webhook",
        // 대상 URL
        url: "https://your-server.com/openclaw/events",
        // 서명 키 (요청 진위 검증용)
        secret: "whsec_xxxxxxxxxxxxxxxx",
        // 구독할 이벤트 유형
        events: [
          "message.received",
          "message.sent",
          "session.created",
          "session.ended",
          "tool.called",
          "tool.completed",
          "error.occurred"
        ],
        // 재시도 설정
        retry: {
          maxAttempts: 3,
          backoffMs: 1000
        }
      }
    ]
  }
}

이벤트 유형 상세 설명

이벤트 유형	트리거 시점	용도
`message.received`	사용자 메시지 수신 시	로그 기록, 메시지 감사
`message.sent`	AI 응답 전송 후	응답 모니터링, 콘텐츠 심사
`session.created`	새 세션 생성 시	사용자 행동 추적
`session.ended`	세션 종료 또는 타임아웃	데이터 아카이브
`tool.called`	MCP 도구 호출 시	보안 감사
`tool.completed`	도구 호출 완료 시	성능 모니터링
`error.occurred`	오류 발생 시	알림 통지

이벤트 페이로드 형식

각 Webhook 요청의 Body는 통일된 형식을 따릅니다:

{
  "id": "evt_abc123def456",
  "type": "message.sent",
  "timestamp": "2026-03-14T10:30:00Z",
  "instanceId": "node-1",
  "data": {
    "agentId": "my-agent",
    "sessionId": "session-001",
    "channel": "telegram",
    "userId": "user_12345",
    "message": {
      "role": "assistant",
      "content": "AI의 응답 내용입니다...",
      "messageId": "msg_xyz789"
    },
    "model": "claude-sonnet-4-20250514",
    "usage": {
      "inputTokens": 200,
      "outputTokens": 450
    }
  }
}

서명 검증

Webhook 요청이 실제로 OpenClaw 인스턴스에서 온 것인지 확인하기 위해, 각 요청에 서명 헤더가 포함됩니다:

X-OpenClaw-Signature: sha256=5a8c3f2b...
X-OpenClaw-Timestamp: 1710400200

검증 예제 (Node.js):

const crypto = require("crypto");

function verifyWebhook(payload, signature, timestamp, secret) {
  const signedPayload = `${timestamp}.${payload}`;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(signedPayload)
    .digest("hex");
  return `sha256=${expected}` === signature;
}

인바운드 Webhook 설정

인바운드 Webhook은 외부 시스템이 OpenClaw의 Agent를 능동적으로 트리거할 수 있게 합니다:

{
  webhooks: {
    inbound: {
      enabled: true,
      // 인바운드 Webhook 경로 접두사
      basePath: "/webhooks/inbound",
      // 엔드포인트 설정
      endpoints: {
        // POST /webhooks/inbound/alert 수신 시 트리거
        "alert": {
          agentId: "alert-handler",
          // 메시지 템플릿, 변수 치환 지원
          template: "알림 수신: {{body.title}} - 심각도: {{body.severity}}"
        },
        "deploy": {
          agentId: "devops-agent",
          template: "{{body.repo}}의 {{body.branch}} 브랜치 배포 {{body.status}}"
        }
      }
    }
  }
}

외부 시스템 호출 예제:

# CI/CD 배포 알림
curl -X POST http://openclaw.example.com/webhooks/inbound/deploy \
  -H "Content-Type: application/json" \
  -d '{
    "repo": "my-app",
    "branch": "main",
    "status": "성공",
    "commit": "abc123"
  }'

실제 통합 시나리오

시나리오 1: 메시지 감사 및 규정 준수

모든 AI 대화 기록을 기업의 감사 시스템으로 전송합니다:

{
  webhooks: {
    endpoints: [{
      name: "audit-log",
      url: "https://audit.company.com/api/logs",
      events: ["message.received", "message.sent"],
      // 특정 Agent의 이벤트만 전송
      filter: {
        agentIds: ["customer-support", "hr-assistant"]
      }
    }]
  }
}

시나리오 2: Slack 알림

AI Agent에 오류가 발생하면 자동으로 Slack 알림을 전송합니다:

{
  webhooks: {
    endpoints: [{
      name: "slack-alert",
      url: "https://hooks.slack.com/services/T00/B00/xxxxx",
      events: ["error.occurred"],
      // Slack 메시지 형식으로 변환
      transform: {
        text: "🚨 OpenClaw 알림: {{data.error.message}}\nAgent: {{data.agentId}}\n시간: {{timestamp}}"
      }
    }]
  }
}

시나리오 3: CRM 시스템 통합

사용자가 채팅을 통해 새 세션을 시작하면, 자동으로 CRM에 기록을 생성합니다:

{
  webhooks: {
    endpoints: [{
      name: "crm-integration",
      url: "https://crm.company.com/api/interactions",
      events: ["session.created"],
      headers: {
        "X-API-Key": "${CRM_API_KEY}"
      }
    }]
  }
}

시나리오 4: 양방향 통합 - 티켓 시스템

인바운드와 아웃바운드 Webhook을 결합하여, AI Agent와 티켓 시스템 간의 양방향 연동을 구현합니다:

사용자가 채팅으로 문제를 설명 → AI가 자동으로 티켓 생성 (아웃바운드 Webhook)
티켓 상태 업데이트 → AI Agent에 알림 (인바운드 Webhook) → AI가 사용자에게 능동적으로 알림

{
  webhooks: {
    // 아웃바운드: 새 세션 → 티켓 생성
    endpoints: [{
      name: "create-ticket",
      url: "https://ticketing.company.com/api/tickets",
      events: ["session.created"],
      filter: { agentIds: ["support-bot"] }
    }],
    // 인바운드: 티켓 업데이트 → Agent에 알림
    inbound: {
      endpoints: {
        "ticket-update": {
          agentId: "support-bot",
          template: "티켓 #{{body.ticketId}} 상태가 {{body.status}}(으)로 업데이트되었습니다"
        }
      }
    }
  }
}

Webhook 디버깅

Webhook 전송 로그 조회

# 최근 Webhook 이벤트 조회
openclaw webhooks list --recent 20

# 실패한 Webhook 조회
openclaw webhooks list --status failed

Dashboard로 모니터링

OpenClaw의 Web Dashboard는 Webhook 모니터링 패널을 제공하여, 이벤트 전송 상태, 응답 시간 및 실패 원인을 실시간으로 확인할 수 있습니다.

로컬 테스트

ngrok이나 유사한 도구를 사용하여 로컬에서 Webhook을 테스트합니다:

# 로컬 프록시 시작
ngrok http 8080

# 생성된 URL을 Webhook 대상으로 설정
# https://xxxx.ngrok.io/openclaw/events

마무리

OpenClaw의 Webhook 메커니즘은 AI Agent와 외부 시스템 간의 다리를 놓아줍니다. 아웃바운드 Webhook을 통해 AI의 행동 데이터를 감사 시스템, 모니터링 플랫폼 및 비즈니스 시스템으로 전송할 수 있고, 인바운드 Webhook을 통해 외부 이벤트가 직접 AI Agent의 응답을 트리거할 수 있습니다. 이러한 이벤트 기반 아키텍처를 통해 OpenClaw이 독립적인 채팅 도구를 넘어 기업의 기술 생태계에 깊이 융합될 수 있습니다.