---
name: gitlink-webhook
version: 1.0.0
description: "Webhook 管理：创建、查看、更新、删除、测试 Webhook，配置自动化触发器。当用户需要配置 GitLink 仓库的 Webhook 自动化通知时触发。"
metadata:
  requires:
    bins: ["gitlink-cli"]
  cliHelp: "gitlink-cli webhook --help"
---

# gitlink-webhook（Webhook 操作）

**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。**
**CRITICAL — 所有 Shortcuts 在执行写入/删除操作前，务必先确认用户意图。**
**CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 `gh`（GitHub CLI）操作 GitLink 资源。`gh` 仅适用于 GitHub 平台。**

> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md) 了解认证和全局参数。

## Shortcuts

| Shortcut | 说明 | 需要认证 |
|----------|------|----------|
| `webhook +list` | 列出仓库的所有 Webhook | 是 |
| `webhook +create` | 创建新 Webhook | 是 |
| `webhook +update` | 更新 Webhook 配置 | 是 |
| `webhook +delete` | 删除 Webhook | 是 |
| `webhook +test` | 测试 Webhook 推送（发送 ping 事件） | 是 |
| `webhook +info` | 查看 Webhook 详情 | 是 |
| `webhook +events` | 列出所有支持的事件类型 | 否 |

## 支持的事件类型

| 事件类型 | 说明 | 触发时机 |
|----------|------|----------|
| `push` | 代码推送事件 | 向仓库推送代码时 |
| `pull_request` | Pull 请求事件 | 创建、更新、关闭 PR 时 |
| `issue` | Issue 事件 | 创建、更新、关闭 Issue 时 |
| `issue_assign` | Issue 指派事件 | Issue 被指派给用户时 |
| `issue_comment` | Issue 评论事件 | Issue 添加评论时 |
| `pull_request_assign` | PR 指派事件 | PR 被指派给审查者时 |
| `pull_request_comment` | PR 评论事件 | PR 添加评论时 |
| `merge_request` | 合并请求事件 | PR 被合并时 |
| `repository` | 仓库事件 | 仓库设置变更时 |
| `branch` | 分支事件 | 创建或删除分支时 |
| `tag` | 标签事件 | 创建或删除标签时 |

## 使用示例

### 基本操作

```bash
# 列出仓库的所有 Webhook
gitlink-cli webhook +list --owner myuser --repo myrepo

# 查看 Webhook 详情
gitlink-cli webhook +info --owner myuser --repo myrepo --id 123

# 列出所有支持的事件类型
gitlink-cli webhook +events
```

### 创建 Webhook

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

# 创建多事件 Webhook
gitlink-cli webhook +create --owner myuser --repo myrepo --url https://example.com/webhook --events push,pull_request,issue

# 创建带密钥的 Webhook
gitlink-cli webhook +create --owner myuser --repo myrepo --url https://example.com/webhook --secret my-secret-key --events push

# 创建带描述的 Webhook
gitlink-cli webhook +create --owner myuser --repo myrepo --url https://example.com/webhook --description "CI/CD automation"
```

### 更新 Webhook

```bash
# 更新 Webhook URL
gitlink-cli webhook +update --owner myuser --repo myrepo --id 123 --url https://new-url.com/webhook

# 更新监听事件
gitlink-cli webhook +update --owner myuser --repo myrepo --id 123 --events push,pull_request

# 激活/停用 Webhook
gitlink-cli webhook +update --owner myuser --repo myrepo --id 123 --active false

# 更新多个属性
gitlink-cli webhook +update --owner myuser --repo myrepo --id 123 --url https://new-url.com/webhook --events push,pull_request --secret new-secret
```

### 测试和删除

```bash
# 测试 Webhook（发送 ping 事件）
gitlink-cli webhook +test --owner myuser --repo myrepo --id 123

# 测试特定事件类型
gitlink-cli webhook +test --owner myuser --repo myrepo --id 123 --event push

# 删除 Webhook
gitlink-cli webhook +delete --owner myuser --repo myrepo --id 123
```

## 典型使用场景

### 场景1: 配置 CI/CD 自动化

```bash
# 为 CI/CD 系统创建 Webhook
gitlink-cli webhook +create \
  --owner myuser --repo myrepo \
  --url https://ci.example.com/gitlink/webhook \
  --events push,pull_request \
  --secret ci-secret-key \
  --description "Trigger CI/CD pipeline"
```

### 场景2: 配置 Issue 通知

```bash
# 创建 Issue 通知 Webhook
gitlink-cli webhook +create \
  --owner myuser --repo myrepo \
  --url https://notification.example.com/issues \
  --events issue,issue_comment,issue_assign \
  --description "Issue notifications"
```

### 场景3: 配置 PR 审查通知

```bash
# 创建 PR 审查 Webhook
gitlink-cli webhook +create \
  --owner myuser --repo myrepo \
  --url https://review.example.com/prs \
  --events pull_request,pull_request_comment,pull_request_assign \
  --description "PR review notifications"
```

## 错误处理

### 常见错误

#### 1. 认证错误
```bash
Error: [401] Authentication failed
```
**解决方案**: 运行 `gitlink-cli auth login` 重新认证

#### 2. 权限不足
```bash
Error: [403] You are not authorized to manage webhooks
```
**解决方案**: 确认您对仓库有管理员权限

#### 3. 无效的事件类型
```bash
Error: no valid events specified
```
**解决方案**: 使用 `gitlink-cli webhook +events` 查看支持的事件类型

#### 4. Webhook 不存在
```bash
Error: [404] Webhook not found
```
**解决方案**: 使用 `gitlink-cli webhook +list` 确认 Webhook ID 是否正确

## AI Agent 使用指南

### 检查现有 Webhook
```bash
# 1. 列出所有 Webhook
gitlink-cli webhook +list --owner $OWNER --repo $REPO --format json

# 2. 检查是否有特定类型的 Webhook
gitlink-cli webhook +list --owner $OWNER --repo $REPO --format json | jq '.data.webhooks[] | select(.hook_url | contains("ci-system"))'
```

### 创建 Webhook 的最佳实践
```bash
# 1. 先查看支持的事件
gitlink-cli webhook +events

# 2. 创建 Webhook 并验证
gitlink-cli webhook +create --owner $OWNER --repo $REPO --url $URL --events $EVENTS

# 3. 测试 Webhook 是否正常工作
gitlink-cli webhook +test --owner $OWNER --repo $REPO --id $WEBHOOK_ID
```

### 安全建议
- **使用密钥**: 为 Webhook 设置密钥以验证请求来源
- **HTTPS**: 始终使用 HTTPS URL 作为 Webhook 回调地址
- **最小权限**: 只监听必要的事件类型
- **定期轮换**: 定期更新 Webhook 密钥

## 参考文档

- [`webhook-list.md`](references/webhook-list.md) - 列出 Webhook 详细说明
- [`webhook-create.md`](references/webhook-create.md) - 创建 Webhook 详细说明
- [`webhook-update.md`](references/webhook-update.md) - 更新 Webhook 详细说明
- [`webhook-delete.md`](references/webhook-delete.md) - 删除 Webhook 详细说明
- [`webhook-test.md`](references/webhook-test.md) - 测试 Webhook 详细说明
- [`webhook-info.md`](references/webhook-info.md) - 查看 Webhook 详细说明
- [`examples/webhook-workflow.md`](examples/webhook-workflow.md) - 完整工作流示例

## 注意事项

1. **API 限制**: GitLink 对 Webhook 数量有限制，通常每个仓库不超过 20 个
2. **URL 要求**: Webhook URL 必须是公网可访问的 HTTPS 地址
3. **超时设置**: Webhook 请求超时时间为 10 秒
4. **重试机制**: GitLink 会在失败时重试 3 次，间隔分别为 1s、5s、10s
5. **事件顺序**: 同一事件的多个 Webhook 按创建顺序依次触发
6. **测试限制**: 测试 Webhook 不会触发实际的业务逻辑，仅验证连通性

## 故障排除

### Webhook 未触发
1. 检查 Webhook 是否激活：`gitlink-cli webhook +info --id <id> --active true`
2. 验证事件类型是否正确：`gitlink-cli webhook +info --id <id>`
3. 测试 Webhook 连通性：`gitlink-cli webhook +test --id <id>`

### Webhook 响应异常
1. 检查回调服务器是否正常运行
2. 验证 Webhook URL 是否可访问
3. 查看 GitLink 服务器日志确认请求是否发送

### 权限问题
1. 确认当前用户是仓库管理员或所有者
2. 检查 Token 是否有足够权限：`gitlink-cli auth status`
