# 웹훅 자동화

웹훅을 사용하면 Synapse 이벤트가 발생할 때 외부 시스템을 트리거할 수
있습니다. 이 가이드는 일반적인 자동화 패턴을 다룹니다.

## 일반적인 패턴

### 패턴 1: 중요 메모리 알림

중요 메모리가 저장될 때 Slack 메시지를 전송:

```python
# Webhook handler (your server)
@app.post("/webhook")
async def handle(request):
    payload = await request.json()
    
    # Verify signature
    if not verify_signature(payload, request.headers):
        return 401
    
    if payload["event"] == "memory.store":
        memory = payload["data"]
        if memory.get("priority") == "critical":
            # Send Slack notification
            await slack.post(
                f"🚨 Critical memory stored: {memory['key']}\n{memory['content'][:200]}"
            )
    
    return 200
```

웹훅 등록:

```bash
curl -X POST https://synapse.schaefer.zone/webhooks \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://my-app.com/webhook",
    "events": "memory.store",
    "secret": "my-hmac-secret"
  }'
```

### 패턴 2: 외부 시스템 동기화

메모리를 Notion, Obsidian 또는 외부 KB에 동기화:

```python
@app.post("/webhook")
async def sync_to_notion(request):
    payload = await request.json()
    
    if payload["event"] == "memory.store":
        memory = payload["data"]
        # Create Notion page
        await notion.create_page(
            title=memory["key"],
            content=memory["content"],
            tags=memory.get("tags", [])
        )
    
    elif payload["event"] == "memory.delete":
        # Delete from Notion
        await notion.delete_page(memory_id=payload["data"]["id"])
    
    return 200
```

### 패턴 3: CI/CD 트리거

"release" 메모리가 저장될 때 배포 트리거:

```python
@app.post("/webhook")
async def trigger_deploy(request):
    payload = await request.json()
    
    if payload["event"] == "memory.store":
        memory = payload["data"]
        if memory.get("key", "").startswith("release_"):
            # Trigger GitLab pipeline
            await gitlab.trigger_pipeline(
                project="synapse",
                ref="main",
                variables={"RELEASE_MEMORY_ID": memory["id"]}
            )
    
    return 200
```

### 패턴 4: 사람의 메시지 시 에이전트 깨우기

사람이 채팅 메시지를 보낼 때 LLM 에이전트 실행 트리거:

```python
@app.post("/webhook")
async def wake_agent(request):
    payload = await request.json()
    
    if payload["event"] == "chat.message_received":
        message = payload["data"]
        # Queue agent processing job
        await job_queue.enqueue(
            "process_message",
            message_id=message["id"],
            content=message["content"]
        )
    
    return 200
```

### 패턴 5: 메트릭 집계

메모리 증가, 채팅 활동, 작업 완료 추적:

```python
@app.post("/webhook")
async def track_metrics(request):
    payload = await request.json()
    event = payload["event"]
    
    metrics = {
        "memory.store": "memories_stored_total",
        "memory.delete": "memories_deleted_total",
        "chat.message_received": "messages_received_total",
        "task.created": "tasks_created_total",
        "task.completed": "tasks_completed_total",
    }
    
    if event in metrics:
        await prometheus.increment(metrics[event])
    
    return 200
```

## 서명 검증

스푸핑을 방지하기 위해 항상 웹훅 서명을 검증하십시오:

```python
import hmac
import hashlib

def verify_signature(payload_body: bytes, headers, secret: str) -> bool:
    signature = headers.get("X-Synapse-Signature", "")
    if not signature.startswith("sha256="):
        return False
    
    expected = hmac.new(
        secret.encode(),
        payload_body,
        hashlib.sha256
    ).hexdigest()
    
    return hmac.compare_digest(f"sha256={expected}", signature)
```

## 재시도 로직

Synapse는 실패한 웹훅을 지수 백오프로 재시도합니다. 귀하의 핸들러는
다음을 수행해야 합니다:

1. **빠르게 200 반환** — 동기적으로 무거운 작업을 하지 마십시오
2. **작업 큐잉** — 백그라운드 작업 시스템 사용
3. **멱등성** — 동일한 이벤트가 두 번 전달될 수 있음

```python
@app.post("/webhook")
async def handle(request):
    payload = await request.json()
    # Queue for async processing
    await job_queue.enqueue("process_webhook", payload)
    # Return immediately
    return 200
```

## 웹훅 디버깅

### 전송 기록 확인

웹훅 전송은 기록됩니다. 웹훅의 최근 전송을 확인하십시오:

```bash
# Get webhook details including recent deliveries
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/webhooks/wh_001
```

### 수동 웹훅 테스트

```bash
# Trigger a test event
curl -X POST https://synapse.schaefer.zone/webhooks/wh_001/test \
  -H "Authorization: Bearer YOUR_MIND_KEY"
```

### 일반적인 문제

| 문제 | 해결 |
|-------|-----|
| 4xx 응답 | 핸들러가 200을 반환하는지 확인 |
| 5xx 응답 | 서버 오류 — 앱 로그 확인 |
| 시간 초과 | 200을 빨리 반환, 작업을 비동기로 큐잉 |
| 중복 전송 | 핸들러를 멱등으로 만들기 |
| 서명 불일치 | 시크릿이 올바른지 확인 |

## 모범 사례

> [!TIP]
> - **항상 서명 검증** — 이를 건너뛰지 마십시오
> - **빠르게 200 반환** — Synapse를 차단하지 마십시오
> - **멱등성** — 중복 전송 처리
> - **특정 이벤트 사용** — `*`가 아닌 `memory.store`
> - **전송 실패 모니터링** — 알림 설정

## 다음 단계

- [Webhooks API](/docs/api/webhooks)
- [Cron 및 Scheduler](/docs/api/cron)
- [영구 LLM 에이전트](/docs/guides/persistent-llm-agent)