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

# gitlink-cli webhook +create

创建新的 Webhook，用于自动化通知和集成。

## 命令格式

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

## 参数说明

| 参数 | 短参数 | 说明 | 是否必须 | 默认值 |
|------|--------|------|----------|--------|
| `--owner` | `-o` | 仓库所有者 | 否 | 自动从 git remote 解析 |
| `--repo` | `-r` | 仓库名称 | 否 | 自动从 git remote 解析 |
| `--url` | `-u` | Webhook 回调 URL | **是** | - |
| `--events` | `-e` | 触发事件（逗号分隔） | 否 | `push` |
| `--active` | - | 是否激活 | 否 | `true` |
| `--content_type` | - | 内容类型 | 否 | `json` |
| `--secret` | - | HMAC 验证密钥 | 否 | 空 |
| `--description` | `-d` | Webhook 描述 | 否 | 空 |

### 事件类型
支持的事件类型（多个事件用逗号分隔）：
- `push` - 代码推送
- `pull_request` - Pull 请求
- `issue` - Issue 事件
- `issue_assign` - Issue 指派
- `issue_comment` - Issue 评论
- `pull_request_assign` - PR 指派
- `pull_request_comment` - PR 评论
- `merge_request` - 合并请求
- `repository` - 仓库事件
- `branch` - 分支事件
- `tag` - 标签事件

## 返回值

### 成功返回
```json
{
  "ok": true,
  "data": {
    "id": "456",
    "hook_url": "https://example.com/webhook",
    "events": ["push", "pull_request"],
    "is_active": true,
    "content_type": "json",
    "description": "CI/CD webhook",
    "created_at": "2024-01-01T00:00:00Z",
    "project": {
      "owner": "myuser",
      "repo": "myrepo"
    }
  },
  "meta": {
    "identity": "user:myuser"
  }
}
```

### 错误返回
```json
{
  "ok": false,
  "error": {
    "code": 400,
    "message": "Invalid webhook URL",
    "suggestion": "Please provide a valid HTTPS URL"
  }
}
```

## 使用示例

### 基本 Webhook
```bash
# 创建最简单的 Webhook（仅监听 push 事件）
gitlink-cli webhook +create --owner myuser --repo myrepo --url https://example.com/webhook

# 在 git 仓库目录中创建（自动解析 owner/repo）
gitlink-cli webhook +create --url https://example.com/webhook
```

### 多事件 Webhook
```bash
# 监听多个事件
gitlink-cli webhook +create \
  --owner myuser --repo myrepo \
  --url https://ci.example.com/webhook \
  --events push,pull_request,issue

# 监听所有 PR 相关事件
gitlink-cli webhook +create \
  --url https://review.example.com/webhook \
  --events pull_request,pull_request_assign,pull_request_comment
```

### 带密钥的 Webhook
```bash
# 创建带 HMAC 验证密钥的 Webhook
gitlink-cli webhook +create \
  --url https://ci.example.com/webhook \
  --events push \
  --secret my-secret-key-12345

# CI/CD 系统的 Webhook（推荐）
gitlink-cli webhook +create \
  --url https://jenkins.example.com/gitlink-webhook \
  --events push,pull_request \
  --secret jenkins-webhook-secret \
  --description "Jenkins CI trigger"
```

### 带描述的 Webhook
```bash
# 创建带描述的 Webhook
gitlink-cli webhook +create \
  --url https://notification.example.com/webhook \
  --events issue,issue_comment \
  --description "Issue notifications to Slack"
```

### 不激活的 Webhook
```bash
# 创建 Webhook 但暂时不激活
gitlink-cli webhook +create \
  --url https://example.com/webhook \
  --events push \
  --active false \
  --description "Webhook for testing"
```

### 不同内容类型
```bash
# JSON 格式（默认）
gitlink-cli webhook +create --url https://example.com/webhook --content-type json

# Form 格式
gitlink-cli webhook +create --url https://example.com/webhook --content-type form
```

## 错误处理

### 常见错误

#### 1. URL 无效
```bash
Error: Invalid webhook URL format
```
**原因**: URL 格式不正确或不是 HTTPS
**解决方案**:
```bash
# 使用 HTTPS URL
gitlink-cli webhook +create --url https://example.com/webhook
```

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

# 使用正确的事件类型
gitlink-cli webhook +create --url https://example.com/webhook --events push,pull_request
```

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

#### 4. Webhook 数量超限
```bash
Error: [400] Webhook limit reached (maximum 20 webhooks per repository)
```
**原因**: 仓库的 Webhook 数量已达上限
**解决方案**:
```bash
# 删除不需要的 Webhook
gitlink-cli webhook +delete --id <unused-webhook-id>
```

## 最佳实践

### 1. 安全性
```bash
# 始终为 Webhook 设置密钥
gitlink-cli webhook +create \
  --url https://ci.example.com/webhook \
  --events push \
  --secret $(openssl rand -hex 32)

# 使用 HTTPS URL
gitlink-cli webhook +create --url https://example.com/webhook
```

### 2. 事件选择
```bash
# 只监听必要的事件
gitlink-cli webhook +create \
  --url https://ci.example.com/webhook \
  --events push  # CI 只需要 push 事件
```

### 3. 描述清晰
```bash
# 添加清晰的描述便于管理
gitlink-cli webhook +create \
  --url https://jenkins.example.com/webhook \
  --events push,pull_request \
  --description "Production CI - Jenkins Pipeline"
```

## AI Agent 使用建议

### 验证 Webhook 创建
```bash
# 创建后立即测试
WEBHOOK_ID=$(gitlink-cli webhook +create --url $URL --events $EVENTS --format json | jq -r '.data.id')
gitlink-cli webhook +test --id $WEBHOOK_ID

# 验证 Webhook 配置
gitlink-cli webhook +info --id $WEBHOOK_ID
```

### 检查重复 Webhook
```bash
# 检查是否已存在相同 URL 的 Webhook
existing=$(gitlink-cli webhook +list --format json | jq -r '.data.webhooks[] | select(.hook_url == "https://example.com/webhook") | .id')
if [ -n "$existing" ]; then
    echo "Webhook already exists: $existing"
else
    gitlink-cli webhook +create --url https://example.com/webhook
fi
```

## 安全建议

1. **使用密钥**: 始终设置 `--secret` 参数以验证请求来源
2. **HTTPS**: 确保使用 HTTPS URL 保护数据传输
3. **最小权限**: 只监听必要的事件类型
4. **定期轮换**: 定期更新 Webhook 密钥
5. **监控日志**: 监控 Webhook 请求日志以发现异常活动

## 注意事项

1. **URL 要求**: Webhook URL 必须是公网可访问的 HTTPS 地址
2. **数量限制**: 每个仓库最多 20 个 Webhook
3. **权限要求**: 需要仓库管理员权限
4. **事件格式**: 多个事件用逗号分隔，不要有空格
5. **立即生效**: 创建后立即可用，除非设置 `--active false`

## 相关命令

- `webhook +list` - 列出所有 Webhook
- `webhook +update` - 更新 Webhook 配置
- `webhook +test` - 测试 Webhook
- `webhook +events` - 查看支持的事件类型