# Webhooks API

Webhooks 让你在 Synapse 中发生事件时接收 HTTP 回调。非常适合触发外部自动化、发送通知或同步到其他系统。

## 端点

### POST /webhooks

注册新 Webhook。

```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

列出当前 Mind 的所有 Webhook。

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

### GET /webhooks/:id

获取单个 Webhook。

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

### PUT /webhooks/:id

更新 Webhook（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

删除 Webhook。

```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` | 任务被标记为完成 |
| `*` | 所有事件 |

## Webhook Payload

事件触发时，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 对每个 payload 签名：

```
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
# 你的 Webhook 处理程序
@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_external(event["data"])
    elif event["event"] == "chat.message_received":
        # 触发 Agent 唤醒
        notify_agent(event["data"])
```

## 下一步

- [Cron 与调度器](/docs/api/cron)
- [Webhook 自动化指南](/docs/guides/webhook-automation)