> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudthinker.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> 구성 가능한 웹훅으로 CloudThinker 이벤트를 외부 시스템에 전송하세요

웹훅을 사용하면 CloudThinker가 이벤트를 실시간으로 외부 시스템에 푸시하여 자동화, 연동, 사용자 정의 워크플로를 구현할 수 있습니다.

## 웹훅 작동 방식

<Steps>
  <Step title="구성">
    대상 URL로 웹훅 엔드포인트를 생성하고 구독할 이벤트를 선택하세요
  </Step>

  <Step title="트리거">
    구독한 이벤트가 발생하면 CloudThinker가 웹훅 페이로드를 준비합니다
  </Step>

  <Step title="전달">
    CloudThinker가 이벤트 데이터를 담아 엔드포인트로 HTTP POST 요청을 전송합니다
  </Step>

  <Step title="처리">
    시스템이 웹훅을 수신하고 처리한 후 성공 응답을 반환합니다
  </Step>
</Steps>

***

## 웹훅 생성

### 콘솔에서 생성

1. **설정 > Webhooks**로 이동
2. **웹훅 생성** 클릭
3. 웹훅 구성:
   * **이름**: 식별을 위한 설명적 이름
   * **URL**: 엔드포인트 URL (HTTPS여야 함)
   * **이벤트**: 구독할 이벤트 선택
   * **시크릿**: 검증용 선택적 서명 시크릿
4. 저장 및 테스트

### 웹훅 구성

| 필드      | 설명                   | 필수  |
| ------- | -------------------- | --- |
| **이름**  | 식별을 위한 친숙한 이름        | 예   |
| **URL** | 이벤트를 수신할 HTTPS 엔드포인트 | 예   |
| **이벤트** | 구독할 이벤트 유형           | 예   |
| **시크릿** | 페이로드 서명을 위한 공유 시크릿   | 권장  |
| **헤더**  | 포함할 사용자 정의 헤더        | 아니요 |
| **활성**  | 웹훅 활성화/비활성화          | 예   |

***

## 이벤트 유형

CloudThinker 전반에 걸쳐 이벤트를 구독할 수 있습니다.

### 권장 사항 이벤트

| 이벤트                          | 트리거           |
| ---------------------------- | ------------- |
| `recommendation.created`     | 새 권장 사항 생성됨   |
| `recommendation.updated`     | 권장 사항 상태 변경됨  |
| `recommendation.implemented` | 권장 사항 완료로 표시됨 |
| `recommendation.comment`     | 권장 사항에 댓글 추가됨 |

### 인시던트 이벤트

| 이벤트                 | 트리거            |
| ------------------- | -------------- |
| `incident.created`  | 새 인시던트 생성됨     |
| `incident.updated`  | 인시던트 세부 정보 변경됨 |
| `incident.resolved` | 인시던트 해결됨으로 표시됨 |
| `incident.comment`  | 인시던트에 댓글 추가됨   |

### 보안 이벤트

| 이벤트                  | 트리거            |
| -------------------- | -------------- |
| `finding.created`    | 새 보안 발견 항목 탐지됨 |
| `finding.resolved`   | 보안 발견 항목 해결됨   |
| `compliance.changed` | 컴플라이언스 상태 변경됨  |

### 작업 이벤트

| 이벤트              | 트리거           |
| ---------------- | ------------- |
| `task.started`   | 예약된 작업 실행 시작됨 |
| `task.completed` | 작업이 성공적으로 완료됨 |
| `task.failed`    | 작업 실행 중 오류 발생 |

### 에이전트 이벤트

| 이벤트                      | 트리거             |
| ------------------------ | --------------- |
| `conversation.completed` | 에이전트 대화 완료됨     |
| `approval.requested`     | 에이전트가 작업 승인 요청  |
| `approval.granted`       | 사용자가 에이전트 작업 승인 |

### 리소스 이벤트

| 이벤트                   | 트리거               |
| --------------------- | ----------------- |
| `resource.discovered` | 새 클라우드 리소스 발견됨    |
| `resource.changed`    | 리소스 구성 변경됨        |
| `resource.deleted`    | 리소스가 더 이상 존재하지 않음 |

***

## 웹훅 페이로드

각 웹훅은 표준화된 페이로드를 포함합니다.

```json theme={null}
{
  "id": "evt_abc123",
  "type": "recommendation.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "workspace_id": "ws_xyz789",
  "data": {
    "id": "rec_def456",
    "title": "Right-size EC2 instance i-0abc123",
    "potential_savings": 150.00,
    "effort": "low",
    "risk": "low",
    "status": "pending"
  }
}
```

### 페이로드 필드

| 필드             | 설명                                   |
| -------------- | ------------------------------------ |
| `id`           | 고유 이벤트 식별자                           |
| `type`         | 이벤트 유형 (예: `recommendation.created`) |
| `timestamp`    | ISO 8601 타임스탬프                       |
| `workspace_id` | 이벤트가 발생한 워크스페이스                      |
| `data`         | 이벤트 별 페이로드                           |

***

## 보안

### 서명 검증

웹훅 시크릿을 구성하면 CloudThinker가 각 페이로드에 서명합니다.

```
X-CloudThinker-Signature: sha256=<signature>
```

엔드포인트에서 서명을 검증하세요.

```python theme={null}
import hmac
import hashlib

def verify_signature(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)
```

### IP 허용 목록

CloudThinker 웹훅은 알려진 IP 범위에서 발송됩니다. 방화벽 규칙 구성을 위한 현재 IP 목록은 지원팀에 문의하세요.

### HTTPS 전용

웹훅 URL은 HTTPS를 사용해야 합니다. 프로덕션 환경에서는 자체 서명 인증서가 지원되지 않습니다.

***

## 재시도 로직

CloudThinker는 전달에 실패한 웹훅을 재시도합니다.

### 재시도 일정

| 시도 횟수 | 지연  |
| ----- | --- |
| 1     | 즉시  |
| 2     | 1분  |
| 3     | 5분  |
| 4     | 30분 |
| 5     | 2시간 |
| 6     | 8시간 |

### 성공 기준

엔드포인트가 다음을 반환하면 전달 성공으로 간주합니다.

* HTTP 2xx 상태 코드
* 30초 이내 응답

### 실패 처리

모든 재시도 실패 후:

* 이벤트가 실패로 표시됩니다
* (구성된 경우) 알림이 전송됩니다
* 이벤트는 웹훅 로그에서 확인 가능합니다

***

## 웹훅 관리

### 웹훅 테스트

실제 사용 전에 웹훅 전달을 테스트하세요.

1. 설정에서 웹훅 선택
2. **테스트 이벤트 전송** 클릭
3. 이벤트 유형 선택
4. 전달 상태 및 페이로드 확인

### 로그 보기

웹훅 활동을 모니터링하세요.

1. **설정 > Webhooks > 로그**로 이동
2. 전달 시도 확인
3. 요청/응답 세부 정보 확인
4. 상태, 이벤트 유형, 날짜로 필터링

### 웹훅 일시 중지

웹훅을 일시적으로 비활성화하려면:

1. 웹훅 선택
2. **활성** 토글을 끄기로 설정
3. 일시 중지 기간 동안 발생한 이벤트는 대기열에 저장되지 않습니다

***

## 웹훅 템플릿

일반적인 연동에 템플릿을 사용하세요.

### Slack

Slack 채널에 이벤트 게시:

```json theme={null}
{
  "url": "https://hooks.slack.com/services/...",
  "events": ["recommendation.created", "incident.created"],
  "transform": {
    "text": "New {{type}}: {{data.title}}"
  }
}
```

### Jira

CloudThinker 이벤트로 Jira 티켓 생성:

```json theme={null}
{
  "url": "https://your-org.atlassian.net/...",
  "events": ["recommendation.created"],
  "headers": {
    "Authorization": "Basic <base64_credentials>"
  }
}
```

### PagerDuty

PagerDuty 인시던트 트리거:

```json theme={null}
{
  "url": "https://events.pagerduty.com/v2/enqueue",
  "events": ["incident.created"],
  "headers": {
    "Content-Type": "application/json"
  }
}
```

***

## 모범 사례

<AccordionGroup>
  <Accordion title="항상 서명 검증하기">
    웹훅 시크릿을 사용하고 서명을 검증하여 요청이 CloudThinker에서 발송된 것임을 확인하세요.
  </Accordion>

  <Accordion title="빠르게 응답하기">
    즉시 2xx 응답을 반환하고 이벤트는 비동기적으로 처리하세요. 처리가 오래 걸리면 타임아웃이 발생합니다.
  </Accordion>

  <Accordion title="중복 처리하기">
    웹훅 전달이 간헐적으로 중복될 수 있습니다. 이벤트 `id`를 사용하여 수신 측에서 중복을 제거하세요.
  </Accordion>

  <Accordion title="실패 모니터링하기">
    웹훅 실패에 대한 알림을 설정하세요. 이벤트 누락을 방지하기 위해 문제를 신속히 조사하고 해결하세요.
  </Accordion>

  <Accordion title="특정 구독 사용하기">
    필요한 이벤트에만 구독하세요. 노이즈와 처리 오버헤드를 줄여줍니다.
  </Accordion>
</AccordionGroup>

***

## 연동 예시

### GitHub Actions

CloudThinker 이벤트에서 워크플로 트리거:

```yaml theme={null}
# .github/workflows/cloudthinker.yml
on:
  repository_dispatch:
    types: [recommendation-created]

jobs:
  process:
    runs-on: ubuntu-latest
    steps:
      - name: Process recommendation
        run: |
          echo "New recommendation: ${{ github.event.client_payload.title }}"
```

### AWS Lambda

서버리스 함수로 웹훅 처리:

```python theme={null}
def lambda_handler(event, context):
    body = json.loads(event['body'])

    if body['type'] == 'recommendation.created':
        # Process new recommendation
        process_recommendation(body['data'])

    return {'statusCode': 200}
```

***

## 관련 항목

<CardGroup cols={2}>
  <Card title="인시던트 웹훅" icon="siren-on" href="/ko/guide/incident/webhook-integrations">
    PagerDuty, Datadog, Prometheus 등의 인바운드 웹훅으로 RCA 자동 트리거
  </Card>

  <Card title="작업 & 스케줄링" icon="calendar-check" href="/ko/guide/automation/tasks">
    반복 작업 예약 및 이벤트 기반 워크플로 생성
  </Card>

  <Card title="알림" icon="bell" href="/ko/guide/notifications">
    권장 사항, 인시던트, 보안 발견 항목에 대한 알림 라우팅 구성
  </Card>

  <Card title="자율 에이전트" icon="robot" href="/ko/guide/automation/autonomous-agents">
    에이전트가 수동 검토 없이 웹훅 이벤트에 자동으로 대응하도록 설정
  </Card>
</CardGroup>