Webhook 当前为 Beta 功能，接口、字段和行为可能在后续版本中调整。
POST /api/v1/forward/webhook/endpoints
请求头
| Header | 是否必填 | 说明 |
|---|
Authorization | 是 | Bearer <PAT 或管理员 SAT> |
Content-Type | 是 | application/json |
Idempotency-Key | 否 | 可选幂等键；相同键只能用于相同请求。 |
请求体参数
| 字段 | 类型 | 是否必填 | 说明 |
|---|
url | string | 是 | 接收事件的 HTTP 或 HTTPS 地址。生产环境建议使用 HTTPS。 |
description | string | 否 | Endpoint 的用途说明。 |
events | string[] | 是 | 订阅事件列表，至少包含一项。支持 * 或 namespace.name 形式的具体事件名；不支持 forward.* 等前缀通配符。只有公开事件目录中的事件具有投递契约。 |
metadata | object | 否 | 自定义字符串键值对。 |
示例请求
curl -s -X POST 'https://api.qoder.com.cn/api/v1/forward/webhook/endpoints' \
-H "Authorization: Bearer $QODER_PAT" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: webhook-endpoint-production' \
-d '{
"url": "https://example.com/webhooks/qoder",
"description": "Schedule notifications",
"events": [
"forward.schedule.created",
"forward.schedule_run.succeeded",
"forward.schedule_run.failed"
],
"metadata": {
"environment": "production"
}
}'
示例响应
HTTP 201 Created
{
"id": "e149c233-1234-4abc-8def-1234567890ab",
"url": "https://example.com/webhooks/qoder",
"description": "Schedule notifications",
"events": [
"forward.schedule.created",
"forward.schedule_run.succeeded",
"forward.schedule_run.failed"
],
"metadata": {
"environment": "production"
},
"active": true,
"signing_secret": "whsec_BASE64_ENCODED_SECRET",
"created_at": "2026-09-01T08:00:00Z"
}
响应字段
| 字段 | 类型 | 说明 |
|---|
id | string | Endpoint ID。请将其作为不透明字符串保存。 |
url | string | 事件接收地址。 |
description | string | Endpoint 描述。 |
events | string[] | 当前订阅事件。 |
metadata | object | 自定义元数据；返回值可能包含平台维护的字段。 |
active | boolean | Endpoint 是否启用；新建时为 true。 |
signing_secret | string | 验证 Webhook 签名的密钥，仅在本次响应中返回。 |
created_at | string | 创建时间，RFC 3339 格式。 |
请在收到响应后立即安全保存 signing_secret。列表、详情和更新接口不会再次返回该字段。
| HTTP | Type | 触发条件 |
|---|
400 | invalid_request_error | URL、事件列表、Metadata 或请求体不合法。 |
401 | authentication_error | 认证信息缺失、无效或已过期。 |
403 | permission_error | 当前令牌不能管理 Webhook。 |
409 | conflict_error | 幂等键与已有请求冲突，或 Endpoint 数量已达上限。 |
413 | invalid_request_error | 请求体过大。 |
429 | rate_limit_error | 请求频率达到限制。 |
