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

gitlink-cli webhook +test

测试 Webhook 连接性，发送测试事件验证 Webhook 是否正常工作。

命令格式

gitlink-cli webhook +test \
  [--owner OWNER] \
  [--repo REPO] \
  --id WEBHOOK_ID \
  [--event EVENT_TYPE]

参数说明

参数	短参数	说明	是否必须	默认值
--owner	-o	仓库所有者	否	自动从 git remote 解析
--repo	-r	仓库名称	否	自动从 git remote 解析
--id	-i	Webhook ID	是	-
--event	-e	测试的事件类型	否	push

支持的测试事件

• push - 推送事件（默认）
• pull_request - Pull 请求事件
• issue - Issue 事件
• 其他支持的事件类型

返回值

成功返回

{
  "ok": true,
  "data": {
    "message": "Webhook test triggered successfully",
    "webhook_id": "456",
    "event_type": "push",
    "delivered": true,
    "response_status": 200,
    "response_body": "Webhook received"
  },
  "meta": {
    "identity": "user:myuser"
  }
}

Webhook 不可达

{
  "ok": true,
  "data": {
    "message": "Webhook test completed with warnings",
    "webhook_id": "456",
    "event_type": "push",
    "delivered": false,
    "error": "Connection timeout",
    "suggestion": "Please check if the webhook URL is accessible"
  }
}

错误返回

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

使用示例

基本测试

# 测试 Webhook（默认使用 push 事件）
gitlink-cli webhook +test --owner myuser --repo myrepo --id 456

# 在 git 仓库目录中测试
gitlink-cli webhook +test --id 456

# 使用短参数
gitlink-cli webhook +test -i 456

测试特定事件类型

# 测试 pull_request 事件
gitlink-cli webhook +test --id 456 --event pull_request

# 测试 issue 事件
gitlink-cli webhook +test --id 456 --event issue

# 测试多种事件类型
for event in push pull_request issue; do
    echo "Testing event: $event"
    gitlink-cli webhook +test --id 456 --event $event
done

批量测试所有 Webhook

# 测试仓库的所有 Webhook
for id in $(gitlink-cli webhook +list --format json | jq -r '.data.webhooks[].id'); do
    echo "Testing webhook: $id"
    gitlink-cli webhook +test --id $id
done

测试新创建的 Webhook

# 创建后立即测试
WEBHOOK_ID=$(gitlink-cli webhook +create --url https://example.com/webhook --events push --format json | jq -r '.data.id')
echo "Testing new webhook: $WEBHOOK_ID"
gitlink-cli webhook +test --id $WEBHOOK_ID

错误处理

常见错误

1. Webhook 不存在

Error: [404] Webhook not found

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

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

2. 无效的事件类型

Error: unsupported event type: custom_event

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

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

# 使用支持的事件类型
gitlink-cli webhook +test --id 456 --event push

3. Webhook URL 不可达

Warning: Webhook delivery failed - Connection timeout

原因: Webhook URL 无法访问或服务器无响应 解决方案:

# 1. 检查 URL 是否正确
gitlink-cli webhook +info --id 456

# 2. 手动测试 URL
curl -X POST https://your-webhook-url.com/test

# 3. 检查服务器防火墙和网络设置

4. SSL 证书问题

Warning: Webhook delivery failed - SSL certificate verify failed

原因: Webhook 服务器的 SSL 证书有问题 解决方案:

# 检查 SSL 证书
curl -v https://your-webhook-url.com/test

# 更新服务器的 SSL 证书

最佳实践

1. 创建后测试

# 创建 Webhook 后立即测试
WEBHOOK_ID=$(gitlink-cli webhook +create --url $URL --events $EVENTS --format json | jq -r '.data.id')
if gitlink-cli webhook +test --id $WEBHOOK_ID; then
    echo "Webhook created and tested successfully"
else
    echo "Webhook test failed, please check configuration"
    gitlink-cli webhook +delete --id $WEBHOOK_ID
fi

2. 更新后测试

# 更新 Webhook 后测试
gitlink-cli webhook +update --id 456 --url $NEW_URL
gitlink-cli webhook +test --id 456

3. 定期测试

# 定期测试所有 Webhook 确保正常工作
for id in $(gitlink-cli webhook +list --format json | jq -r '.data.webhooks[].id'); do
    if ! gitlink-cli webhook +test --id $id; then
        echo "WARNING: Webhook $id test failed"
    fi
done

AI Agent 使用建议

自动化测试流程

# AI Agent 测试 Webhook 的完整流程
test_and_fix_webhook() {
    WEBHOOK_ID=$1
    MAX_RETRIES=3
    RETRY_COUNT=0

    while [ $RETRY_COUNT -lt $MAX_RETRIES ]; do
        echo "Testing webhook $WEBHOOK_ID (attempt $((RETRY_COUNT + 1))/$MAX_RETRIES)"

        # 测试 Webhook
        if gitlink-cli webhook +test --id $WEBHOOK_ID; then
            echo "✓ Webhook test successful"
            return 0
        fi

        # 测试失败，等待后重试
        RETRY_COUNT=$((RETRY_COUNT + 1))
        if [ $RETRY_COUNT -lt $MAX_RETRIES ]; then
            echo "Test failed, waiting 5 seconds before retry..."
            sleep 5
        fi
    done

    echo "✗ Webhook test failed after $MAX_RETRIES attempts"
    return 1
}

监控 Webhook 健康

# 定期检查所有 Webhook 的健康状态
check_all_webhooks_health() {
    REPORT_FILE="webhook_health_report_$(date +%Y%m%d_%H%M%S).txt"

    echo "Webhook Health Check Report - $(date)" > $REPORT_FILE
    echo "=================================" >> $REPORT_FILE

    for id in $(gitlink-cli webhook +list --format json | jq -r '.data.webhooks[].id'); do
        webhook_info=$(gitlink-cli webhook +info --id $id --format json)
        webhook_url=$(echo $webhook_info | jq -r '.data.hook_url')
        webhook_status=$(echo $webhook_info | jq -r '.data.is_active')

        echo -e "\nWebhook ID: $id" >> $REPORT_FILE
        echo "URL: $webhook_url" >> $REPORT_FILE
        echo "Active: $webhook_status" >> $REPORT_FILE
        echo "Test Result:" >> $REPORT_FILE

        if gitlink-cli webhook +test --id $id >> $REPORT_FILE 2>&1; then
            echo "Status: HEALTHY ✓" >> $REPORT_FILE
        else
            echo "Status: UNHEALTHY ✗" >> $REPORT_FILE
        fi
    done

    cat $REPORT_FILE
}

故障诊断

# 诊断 Webhook 问题
diagnose_webhook() {
    WEBHOOK_ID=$1

    echo "=== Webhook Diagnosis ==="
    echo "Webhook ID: $WEBHOOK_ID"
    echo

    # 1. 检查 Webhook 是否存在
    echo "1. Checking webhook existence..."
    if ! gitlink-cli webhook +info --id $WEBHOOK_ID >/dev/null 2>&1; then
        echo "   ✗ Webhook not found"
        return 1
    fi
    echo "   ✓ Webhook exists"

    # 2. 获取 Webhook 配置
    echo "2. Webhook configuration:"
    gitlink-cli webhook +info --id $WEBHOOK_ID

    # 3. 测试网络连通性
    echo "3. Testing network connectivity..."
    WEBHOOK_URL=$(gitlink-cli webhook +info --id $WEBHOOK_ID --format json | jq -r '.data.hook_url')
    if curl -s -o /dev/null -w "%{http_code}" "$WEBHOOK_URL" | grep -q "200\|301\|302"; then
        echo "   ✓ URL is accessible"
    else
        echo "   ✗ URL is not accessible"
    fi

    # 4. 测试 Webhook
    echo "4. Testing webhook delivery..."
    if gitlink-cli webhook +test --id $WEBHOOK_ID; then
        echo "   ✓ Webhook test successful"
    else
        echo "   ✗ Webhook test failed"
    fi
}

注意事项

1. 测试限制: 测试事件不会触发实际的业务逻辑，仅验证连通性
2. 请求格式: 测试请求的格式与真实事件略有不同
3. 响应时间: Webhook 应在 10 秒内响应，否则超时
4. 重试机制: 测试失败不会触发 GitLink 的重试机制
5. 权限要求: 需要仓库管理员权限

常见使用场景

场景1: 验证新 Webhook

# 创建 Webhook 后验证配置
WEBHOOK_ID=$(gitlink-cli webhook +create \
  --url https://ci.example.com/webhook \
  --events push,pull_request \
  --format json | jq -r '.data.id')

# 测试各种事件类型
for event in push pull_request; do
    echo "Testing $event event..."
    gitlink-cli webhook +test --id $WEBHOOK_ID --event $event
done

场景2: 故障排查

# Webhook 未触发时进行测试
# 1. 检查 Webhook 是否激活
gitlink-cli webhook +info --id 456

# 2. 测试 Webhook 连通性
gitlink-cli webhook +test --id 456

# 3. 查看详细错误信息
gitlink-cli webhook +test --id 456 --debug

场景3: 批量验证

# 验证所有 Webhook 在服务器迁移后是否正常
for id in $(gitlink-cli webhook +list --format json | jq -r '.data.webhooks[].id'); do
    echo "Testing webhook $id..."
    if ! gitlink-cli webhook +test --id $id; then
        echo "WARNING: Webhook $id needs attention"
        # 可以在这里添加自动修复逻辑
    fi
done

安全建议

1. 避免敏感数据: 测试事件可能包含真实数据，注意隐私保护
2. 测试频率: 不要过于频繁测试，避免对服务器造成压力
3. 错误信息: 测试失败时的错误信息可能暴露系统细节
4. 访问控制: 确保测试 URL 只暴露必要的信息

相关命令

• webhook +list - 列出所有 Webhook
• webhook +info - 查看 Webhook 详情
• webhook +create - 创建新 Webhook
• webhook +update - 更新 Webhook 配置
• webhook +events - 查看支持的事件类型