# gitlink-cli webhook +update

更新现有 Webhook 的配置。

## 命令格式

```bash
gitlink-cli webhook +update \
  --owner OWNER \
  --repo REPO \
  --id WEBHOOK_ID \
  [--url URL] \
  [--events EVENTS] \
  [--active ACTIVE] \
  [--content_type CONTENT_TYPE] \
  [--secret SECRET] \
  [--description DESCRIPTION]
```

## 参数说明

| 参数 | 短参数 | 说明 | 是否必须 | 默认值 |
|------|--------|------|----------|--------|
| `--owner` | `-o` | 仓库所有者 | 否 | 自动从 git remote 解析 |
| `--repo` | `-r` | 仓库名称 | 否 | 自动从 git remote 解析 |
| `--id` | `-i` | Webhook ID | **是** | - |
| `--url` | `-u` | 新的 Webhook URL | 否 | 不修改 |
| `--events` | `-e` | 新的触发事件 | 否 | 不修改 |
| `--active` | - | 是否激活 | 否 | 不修改 |
| `--content_type` | - | 内容类型 | 否 | 不修改 |
| `--secret` | - | 新的密钥 | 否 | 不修改 |
| `--description` | `-d` | 新的描述 | 否 | 不修改 |

## 返回值

### 成功返回
```json
{
  "ok": true,
  "data": {
    "id": "456",
    "hook_url": "https://new-url.example.com/webhook",
    "events": ["push", "pull_request", "issue"],
    "is_active": false,
    "content_type": "json",
    "description": "Updated webhook description",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-02T12:00:00Z"
  },
  "meta": {
    "identity": "user:myuser"
  }
}
```

### 错误返回
```json
{
  "ok": false,
  "error": {
    "code": 404,
    "message": "Webhook not found",
    "suggestion": "Please check the webhook ID"
  }
}
```

## 使用示例

### 更新 URL
```bash
# 修改 Webhook 回调地址
gitlink-cli webhook +update --owner myuser --repo myrepo --id 456 --url https://new-url.example.com/webhook

# 在 git 仓库目录中更新
gitlink-cli webhook +update --id 456 --url https://new-url.example.com/webhook
```

### 更新事件
```bash
# 添加更多事件类型
gitlink-cli webhook +update --id 456 --events push,pull_request,issue,issue_comment

# 减少事件类型（只监听 push）
gitlink-cli webhook +update --id 456 --events push
```

### 激活/停用 Webhook
```bash
# 停用 Webhook
gitlink-cli webhook +update --id 456 --active false

# 重新激活 Webhook
gitlink-cli webhook +update --id 456 --active true
```

### 更新密钥
```bash
# 更新 Webhook 密钥（推荐定期轮换）
gitlink-cli webhook +update --id 456 --secret new-secret-key-2024
```

### 更新描述
```bash
# 更新 Webhook 描述
gitlink-cli webhook +update --id 456 --description "Updated for new CI/CD pipeline"
```

### 批量更新多个属性
```bash
# 同时更新多个属性
gitlink-cli webhook +update \
  --id 456 \
  --url https://new-url.example.com/webhook \
  --events push,pull_request,issue \
  --secret new-secret \
  --description "Comprehensive webhook update"
```

## 错误处理

### 常见错误

#### 1. Webhook 不存在
```bash
Error: [404] Webhook not found
```
**原因**: 指定的 Webhook ID 不存在
**解决方案**:
```bash
# 先列出所有 Webhook 找到正确 ID
gitlink-cli webhook +list
```

#### 2. 无效的事件类型
```bash
Error: no valid events specified
```
**原因**: 指定了不支持的事件类型
**解决方案**:
```bash
# 查看支持的事件
gitlink-cli webhook +events
```

#### 3. 权限不足
```bash
Error: [403] You don't have permission to update webhooks
```
**原因**: 用户不是仓库管理员
**解决方案**: 确认您有仓库管理员权限

#### 4. 没有指定更新字段
```bash
Error: no fields specified for update
```
**原因**: 没有提供任何要更新的字段
**解决方案**: 至少指定一个要更新的字段

## 最佳实践

### 1. 密钥轮换
```bash
# 定期更新密钥（建议每3个月）
gitlink-cli webhook +update --id 456 --secret $(openssl rand -hex 32)
```

### 2. 临时停用
```bash
# 临时停用 Webhook 进行维护
gitlink-cli webhook +update --id 456 --active false

# 维护完成后重新激活
gitlink-cli webhook +update --id 456 --active true
```

### 3. 渐进式更新
```bash
# 先测试新配置
gitlink-cli webhook +update --id 456 --url https://new-url.example.com/webhook --active false
gitlink-cli webhook +test --id 456

# 确认无误后激活
gitlink-cli webhook +update --id 456 --active true
```

## AI Agent 使用建议

### 批量更新 Webhook
```bash
# 为所有 Webhook 添加新事件
for id in $(gitlink-cli webhook +list --format json | jq -r '.data.webhooks[].id'); do
    # 获取当前事件
    current_events=$(gitlink-cli webhook +info --id $id --format json | jq -r '.data.events | join(",")')
    # 添加新事件
    gitlink-cli webhook +update --id $id --events "$current_events,issue_comment"
done
```

### 验证更新
```bash
# 更新后立即验证
WEBHOOK_ID=456
gitlink-cli webhook +update --id $WEBHOOK_ID --url $NEW_URL
gitlink-cli webhook +info --id $WEBHOOK_ID
gitlink-cli webhook +test --id $WEBHOOK_ID
```

### 检查更新前后差异
```bash
# 查看更新前后配置差异
BEFORE=$(gitlink-cli webhook +info --id 456 --format json)
gitlink-cli webhook +update --id 456 --url $NEW_URL
AFTER=$(gitlink-cli webhook +info --id 456 --format json)

# 对比差异（需要 jq 工具）
echo "Before:" && echo "$BEFORE" | jq '.data'
echo "After:" && echo "$AFTER" | jq '.data'
```

## 安全建议

1. **密钥轮换**: 定期更新 Webhook 密钥，建议每3个月一次
2. **测试新配置**: 更新重要配置前先停用，测试后再激活
3. **备份配置**: 更新前记录原配置，便于回滚
4. **权限验证**: 确保只有授权用户能修改 Webhook
5. **审计日志**: 记录所有 Webhook 配置变更

## 注意事项

1. **部分更新**: 只更新指定的字段，未指定的字段保持不变
2. **ID 不变**: 更新不会改变 Webhook ID
3. **立即生效**: 更新后立即生效，除非停用 Webhook
4. **测试验证**: 建议更新后测试 Webhook 是否正常工作
5. **权限要求**: 需要仓库管理员权限

## 常见使用场景

### 场景1: 迁移 Webhook 到新服务器
```bash
# 更新 Webhook URL 到新服务器
gitlink-cli webhook +update --id 456 --url https://new-server.example.com/webhook
# 测试新地址
gitlink-cli webhook +test --id 456
```

### 场景2: 调整事件监听
```bash
# 原来只监听 push，现在增加 PR 监听
gitlink-cli webhook +update --id 456 --events push,pull_request
```

### 场景3: 安全密钥轮换
```bash
# 定期更新密钥提高安全性
NEW_SECRET=$(openssl rand -hex 32)
gitlink-cli webhook +update --id 456 --secret "$NEW_SECRET"
# 更新接收服务器的密钥配置
# 然后测试
gitlink-cli webhook +test --id 456
```

### 场景4: 临时维护
```bash
# 临时停用 Webhook
gitlink-cli webhook +update --id 456 --active false --description "Maintenance in progress"

# 维护完成后重新激活
gitlink-cli webhook +update --id 456 --active true --description "Production webhook"
```

## 相关命令

- `webhook +list` - 列出所有 Webhook
- `webhook +create` - 创建新 Webhook
- `webhook +info` - 查看 Webhook 详情
- `webhook +test` - 测试 Webhook
