gitlink-cli/skills/gitlink-webhook/references/webhook-update.md

gitlink-cli webhook +update

更新现有 Webhook 的配置。

命令格式

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	新的描述	否	不修改

返回值

成功返回

{
  "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"
  }
}

错误返回

{
  "ok": false,
  "error": {
    "code": 404,
    "message": "Webhook not found",
    "suggestion": "Please check the webhook ID"
  }
}

使用示例

更新 URL

# 修改 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

更新事件

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

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

激活/停用 Webhook

# 停用 Webhook
gitlink-cli webhook +update --id 456 --active false

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

更新密钥

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

更新描述

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

批量更新多个属性

# 同时更新多个属性
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 不存在

Error: [404] Webhook not found

原因: 指定的 Webhook ID 不存在 解决方案:

# 先列出所有 Webhook 找到正确 ID
gitlink-cli webhook +list

2. 无效的事件类型

Error: no valid events specified

原因: 指定了不支持的事件类型 解决方案:

# 查看支持的事件
gitlink-cli webhook +events

3. 权限不足

Error: [403] You don't have permission to update webhooks

原因: 用户不是仓库管理员 解决方案: 确认您有仓库管理员权限

4. 没有指定更新字段

Error: no fields specified for update

原因: 没有提供任何要更新的字段 解决方案: 至少指定一个要更新的字段

最佳实践

1. 密钥轮换

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

2. 临时停用

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

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

3. 渐进式更新

# 先测试新配置
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

# 为所有 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

验证更新

# 更新后立即验证
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

检查更新前后差异

# 查看更新前后配置差异
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 到新服务器

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

场景2: 调整事件监听

# 原来只监听 push，现在增加 PR 监听
gitlink-cli webhook +update --id 456 --events push,pull_request

场景3: 安全密钥轮换

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

场景4: 临时维护

# 临时停用 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