# Webhooks API

웹훅을 사용하면 Synapse에서 이벤트가 발생할 때 HTTP 콜백을 받을 수
있습니다. 외부 자동화 트리거, 알림 전송, 또는 다른 시스템으로의 동기화에
적합합니다.

## 엔드포인트

### POST /webhooks

새 웹훅을 등록합니다.

```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.*",
    "secret": "my-hmac-secret-min-8-chars"
  }'
```

응답:

```json
{
  "id": "wh_001",
  "url": "https://my-app.com/webhook",
  "events": ["memory.*"],
  "enabled": true,
  "created_at": "2026-06-27T..."
}
```

### GET /webhooks

현재 마인드의 모든 웹훅을 나열합니다.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/webhooks
```

### GET /webhooks/:id

단일 웹훅을 가져옵니다.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/webhooks/wh_001
```

### PUT /webhooks/:id

웹훅을 업데이트합니다 (URL, 이벤트, 시크릿, 또는 활성화 플래그).

```bash
curl -X PUT https://synapse.schaefer.zone/webhooks/wh_001 \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'
```

### DELETE /webhooks/:id

웹훅을 삭제합니다.

```bash
curl -X DELETE -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/webhooks/wh_001
```

## 이벤트 유형

| 패턴 | 발생 시점 |
|---------|------------|
| `memory.*` | 모든 메모리 이벤트 |
| `memory.store` | 새 메모리 저장 |
| `memory.update` | 메모리 업데이트 |
| `memory.delete` | 메모리 삭제 |
| `chat.*` | 모든 채팅 이벤트 |
| `chat.message_received` | 사람이 보낸 새 메시지 |
| `task.*` | 모든 작업 이벤트 |
| `task.created` | 새 작업 생성 |
| `task.completed` | 작업 완료 표시 |
| `*` | 모든 이벤트 |

## 웹훅 페이로드

이벤트가 발생하면 Synapse가 귀하의 URL로 POST합니다:

```json
{
  "event": "memory.store",
  "timestamp": "2026-06-27T...",
  "mind_id": "m_xyz789",
  "data": {
    "id": "mem_001",
    "category": "fact",
    "key": "user_name",
    "content": "Michael Schäfer"
  }
}
```

## 서명 검증

`secret`을 설정하면 Synapse가 각 페이로드를 HMAC-SHA256으로 서명합니다:

```
X-Synapse-Signature: sha256=<hex-hmac>
```

핸들러에서 검증:

```python
import hmac, hashlib

def verify_signature(payload_body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload_body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)
```

## 패턴: 실시간 동기화

```python
# Your webhook handler
@app.post("/webhook")
async def handle_webhook(request):
    body = await request.body()
    signature = request.headers.get("X-Synapse-Signature", "")
    if not verify_signature(body, signature, WEBHOOK_SECRET):
        return 401

    event = json.loads(body)
    if event["event"] == "memory.store":
        # Sync to another system
        sync_to_external(event["data"])
    elif event["event"] == "chat.message_received":
        # Trigger agent wake-up
        notify_agent(event["data"])
```

## 다음 단계

- [Cron 및 Scheduler](/docs/api/cron)
- [웹훅 자동화 가이드](/docs/guides/webhook-automation)