Skip to main content
Webhooks

更新 Webhook Endpoint

更新 Endpoint 的接收地址、描述、订阅事件或元数据。

Webhook 当前为 Beta 功能,接口、字段和行为可能在后续版本中调整。
PUT /api/v1/forward/webhook/endpoints/{endpoint_id} 仅修改请求中出现的字段。省略字段会保留原值。

请求头

Header是否必填说明
AuthorizationBearer <PAT 或管理员 SAT>
Content-Typeapplication/json

路径参数

参数类型是否必填说明
endpoint_idstringWebhook Endpoint ID。

请求体参数

字段类型是否必填说明
urlstring新的事件接收地址。生产环境建议使用 HTTPS。
descriptionstring新的用途说明。
eventsstring[]替换完整订阅列表,至少包含一项。支持 * 或具体事件名,不支持前缀通配符。
activebooleanEndpoint 是否启用;也可使用单独的启用或停用接口。
metadataobject合并更新自定义元数据;值为字符串,传入 null 可删除对应键。

示例请求

curl -s -X PUT 'https://api.qoder.com.cn/api/v1/forward/webhook/endpoints/e149c233-1234-4abc-8def-1234567890ab' \
  -H "Authorization: Bearer $QODER_PAT" \
  -H 'Content-Type: application/json' \
  -d '{
    "description": "Schedule completion notifications",
    "events": [
      "forward.schedule_run.succeeded",
      "forward.schedule_run.failed"
    ]
  }'

示例响应

HTTP 200 OK
{
  "id": "e149c233-1234-4abc-8def-1234567890ab",
  "url": "https://example.com/webhooks/qoder",
  "description": "Schedule completion notifications",
  "events": [
    "forward.schedule_run.succeeded",
    "forward.schedule_run.failed"
  ],
  "metadata": {
    "environment": "production"
  },
  "active": true,
  "last_success_at": "2026-09-01T09:07:59Z",
  "last_failure_at": null,
  "consecutive_fail": 0,
  "created_at": "2026-09-01T08:00:00Z",
  "updated_at": "2026-09-01T10:00:00Z"
}
响应字段见获取 Webhook Endpoint。更新不会返回或轮换 signing_secret

错误

HTTPType触发条件
400invalid_request_errorURL、事件列表、Metadata 或请求体不合法。
401authentication_error认证信息缺失、无效或已过期。
403permission_error当前令牌不能管理 Webhook。
404not_found_errorEndpoint 不存在或当前账号不可见。
413invalid_request_error请求体过大。
500/502/503api_error服务暂时不可用。

相关