{
  "openapi": "3.1.0",
  "info": {
    "title": "NexusMC Webhook 管理与事件",
    "version": "1.0.0",
    "description": "网站 Cookie 管理参考与出站事件协议；不增加 PAT/OAuth scope，不改变现有业务路由。跨域文档站不读取 HttpOnly Cookie，也不为了调试开放管理 CORS。"
  },
  "servers": [
    {
      "url": "https://wwwdev.nexusmc.cn"
    }
  ],
  "paths": {
    "/api/webhooks/endpoints": {
      "get": {
        "operationId": "listWebhookEndpoints",
        "summary": "列出我的 Webhook 端点",
        "tags": [
          "Webhook 管理"
        ],
        "description": "只接受当前网站 Cookie 会话并检查 owner。PAT/OAuth access 不可调用。",
        "security": [
          {
            "websiteSession": []
          }
        ],
        "responses": {
          "200": {
            "description": "成功；无额外 data 信封。",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/WebhookEndpoint"
                      }
                    },
                    "quota": {
                      "const": 10
                    }
                  },
                  "required": [
                    "items",
                    "quota"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "items": [],
                  "quota": 10
                }
              }
            }
          },
          "400": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 400,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          },
          "401": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 401,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          },
          "403": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 403,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          },
          "404": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 404,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          },
          "429": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 429,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          },
          "503": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 503,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "javascript",
            "label": "Fetch（网站同源）",
            "source": "// 在网站同源页面执行，Cookie 由浏览器自动附带。\nconst response = await fetch(\"/api/webhooks/endpoints\", {\n  method: 'GET',\n  credentials: 'same-origin',\n})\nif (!response.ok) throw new Error(`请求失败：${response.status}`)\nconst result = await response.json()"
          },
          {
            "lang": "shell",
            "label": "curl（网站会话）",
            "source": "# 使用网站当前会话；不要填写 PAT/OAuth token。\ncurl --fail-with-body --request GET 'http://localhost:3001/api/webhooks/endpoints' \\\n  --header \"Cookie: $NEXUSMC_COOKIE\""
          }
        ]
      },
      "post": {
        "operationId": "createWebhookEndpoint",
        "summary": "申请创建 Webhook 端点",
        "tags": [
          "Webhook 管理"
        ],
        "description": "必须绑定本人已经审核通过且启用的 OAuth 或机器人应用。创建后端点处于 pending 且禁用，平台审核通过后才启用。出站事件仍由独立 signingSecret 进行 HMAC-SHA256 签名；不发送 OAuth client secret。",
        "security": [
          {
            "websiteSession": [],
            "csrfHeader": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 100,
                    "description": "去首尾空格后校验长度。"
                  },
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "maxLength": 2048,
                    "description": "公网域名 HTTPS/443；禁止凭据、片段、IP literal、非公网 DNS 和重定向。每次投递重新验证 DNS 并固定实际连接目标。"
                  },
                  "clientId": {
                    "type": "string",
                    "minLength": 1,
                    "description": "必填；本人已经审核通过且启用的 OAuth 或机器人应用 ID。Webhook 创建后进入待审并保持禁用，审核仅在创建时进行。"
                  }
                },
                "required": [
                  "name",
                  "url",
                  "clientId"
                ],
                "additionalProperties": false
              },
              "example": {
                "name": "example-value",
                "url": "https://receiver.example.com/webhooks/nexusmc",
                "clientId": "example-value"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功；无额外 data 信封。",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "endpoint": {
                      "$ref": "#/components/schemas/WebhookEndpoint"
                    },
                    "signingSecret": {
                      "type": "string",
                      "description": "仅创建或轮换时显示一次；作为 UTF-8 字符串保存到接收端私密环境，不是 OAuth client secret。"
                    }
                  },
                  "required": [
                    "endpoint",
                    "signingSecret"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "endpoint": {
                    "id": "example-value",
                    "name": "example-value",
                    "url": "https://receiver.example.com/webhooks/nexusmc",
                    "clientId": null,
                    "enabled": true,
                    "reviewStatus": "pending",
                    "reviewedAt": null,
                    "reviewNote": "example-value",
                    "version": "1",
                    "createdAt": "2026-10-16T00:00:00.000Z",
                    "updatedAt": "2026-10-16T00:00:00.000Z"
                  },
                  "signingSecret": "example-value"
                }
              }
            }
          },
          "400": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 400,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          },
          "401": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 401,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          },
          "403": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 403,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          },
          "404": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 404,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          },
          "429": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 429,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          },
          "503": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 503,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          }
        },
        "x-required-proof": "api-token",
        "x-proof-ttl-seconds": 300,
        "x-codeSamples": [
          {
            "lang": "javascript",
            "label": "Fetch（网站同源）",
            "source": "// 在网站同源页面执行，Cookie 由浏览器自动附带。请先在网站完成 api-token 二次验证。\nconst csrfToken = decodeURIComponent(document.cookie.split(';').map(value => value.trim()).find(value => value.startsWith('csrf_token='))?.slice('csrf_token='.length) ?? '')\nif (!csrfToken) throw new Error('请先在网站登录')\nconst response = await fetch(\"/api/webhooks/endpoints\", {\n  method: 'POST',\n  credentials: 'same-origin',\n  headers: { 'x-csrf-token': csrfToken, 'Content-Type': 'application/json' },\n  body: JSON.stringify({\"name\":\"example-value\",\"url\":\"https://receiver.example.com/webhooks/nexusmc\",\"clientId\":\"example-value\"}),\n})\nif (!response.ok) throw new Error(`请求失败：${response.status}`)\nconst result = await response.json()"
          },
          {
            "lang": "shell",
            "label": "curl（网站会话）",
            "source": "# 使用网站当前会话；先完成 api-token 二次验证，再提供匹配的 CSRF。\ncurl --fail-with-body --request POST 'http://localhost:3001/api/webhooks/endpoints' \\\n  --header \"Cookie: $NEXUSMC_COOKIE\" \\\n  --header \"x-csrf-token: $NEXUSMC_CSRF_TOKEN\" \\\n  --header 'Content-Type: application/json' \\\n  --data '{\"name\":\"example-value\",\"url\":\"https://receiver.example.com/webhooks/nexusmc\",\"clientId\":\"example-value\"}'"
          }
        ]
      }
    },
    "/api/webhooks/endpoints/{id}": {
      "patch": {
        "operationId": "updateWebhookEndpoint",
        "summary": "修改 Webhook 端点",
        "tags": [
          "Webhook 管理"
        ],
        "description": "只接受当前网站 Cookie 会话；须为 owner，并持有匹配 Cookie 的 x-csrf-token 及当前会话用途 api-token 的二次验证（300 秒）。Origin/Fetch Metadata 和锁后期限复核仍生效。PAT/OAuth access 不可调用。",
        "security": [
          {
            "websiteSession": [],
            "csrfHeader": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1
            },
            "example": "example-id"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 100,
                    "description": "去首尾空格后校验长度。"
                  },
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "maxLength": 2048,
                    "description": "公网域名 HTTPS/443；禁止凭据、片段、IP literal、非公网 DNS 和重定向。每次投递重新验证 DNS 并固定实际连接目标。"
                  },
                  "enabled": {
                    "type": "boolean"
                  }
                },
                "required": [],
                "additionalProperties": false,
                "minProperties": 1
              },
              "example": {
                "name": "example-value"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功；无额外 data 信封。",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "endpoint": {
                      "$ref": "#/components/schemas/WebhookEndpoint"
                    }
                  },
                  "required": [
                    "endpoint"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "endpoint": {
                    "id": "example-value",
                    "name": "example-value",
                    "url": "https://receiver.example.com/webhooks/nexusmc",
                    "clientId": null,
                    "enabled": true,
                    "reviewStatus": "pending",
                    "reviewedAt": null,
                    "reviewNote": "example-value",
                    "version": "1",
                    "createdAt": "2026-10-16T00:00:00.000Z",
                    "updatedAt": "2026-10-16T00:00:00.000Z"
                  }
                }
              }
            }
          },
          "400": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 400,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          },
          "401": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 401,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          },
          "403": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 403,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          },
          "404": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 404,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          },
          "429": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 429,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          },
          "503": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 503,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          }
        },
        "x-required-proof": "api-token",
        "x-proof-ttl-seconds": 300,
        "x-codeSamples": [
          {
            "lang": "javascript",
            "label": "Fetch（网站同源）",
            "source": "// 在网站同源页面执行，Cookie 由浏览器自动附带。请先在网站完成 api-token 二次验证。\nconst csrfToken = decodeURIComponent(document.cookie.split(';').map(value => value.trim()).find(value => value.startsWith('csrf_token='))?.slice('csrf_token='.length) ?? '')\nif (!csrfToken) throw new Error('请先在网站登录')\nconst response = await fetch(\"/api/webhooks/endpoints/REPLACE_WITH_ID\", {\n  method: 'PATCH',\n  credentials: 'same-origin',\n  headers: { 'x-csrf-token': csrfToken, 'Content-Type': 'application/json' },\n  body: JSON.stringify({\"name\":\"example-value\"}),\n})\nif (!response.ok) throw new Error(`请求失败：${response.status}`)\nconst result = await response.json()"
          },
          {
            "lang": "shell",
            "label": "curl（网站会话）",
            "source": "# 使用网站当前会话；先完成 api-token 二次验证，再提供匹配的 CSRF。\ncurl --fail-with-body --request PATCH 'http://localhost:3001/api/webhooks/endpoints/REPLACE_WITH_ID' \\\n  --header \"Cookie: $NEXUSMC_COOKIE\" \\\n  --header \"x-csrf-token: $NEXUSMC_CSRF_TOKEN\" \\\n  --header 'Content-Type: application/json' \\\n  --data '{\"name\":\"example-value\"}'"
          }
        ]
      },
      "delete": {
        "operationId": "deleteWebhookEndpoint",
        "summary": "删除 Webhook 端点",
        "tags": [
          "Webhook 管理"
        ],
        "description": "只接受当前网站 Cookie 会话；须为 owner，并持有匹配 Cookie 的 x-csrf-token 及当前会话用途 api-token 的二次验证（300 秒）。Origin/Fetch Metadata 和锁后期限复核仍生效。PAT/OAuth access 不可调用。",
        "security": [
          {
            "websiteSession": [],
            "csrfHeader": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1
            },
            "example": "example-id"
          }
        ],
        "responses": {
          "200": {
            "description": "成功；无额外 data 信封。",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "const": true
                    }
                  },
                  "required": [
                    "success"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true
                }
              }
            }
          },
          "400": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 400,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          },
          "401": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 401,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          },
          "403": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 403,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          },
          "404": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 404,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          },
          "429": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 429,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          },
          "503": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 503,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          }
        },
        "x-required-proof": "api-token",
        "x-proof-ttl-seconds": 300,
        "x-codeSamples": [
          {
            "lang": "javascript",
            "label": "Fetch（网站同源）",
            "source": "// 在网站同源页面执行，Cookie 由浏览器自动附带。请先在网站完成 api-token 二次验证。\nconst csrfToken = decodeURIComponent(document.cookie.split(';').map(value => value.trim()).find(value => value.startsWith('csrf_token='))?.slice('csrf_token='.length) ?? '')\nif (!csrfToken) throw new Error('请先在网站登录')\nconst response = await fetch(\"/api/webhooks/endpoints/REPLACE_WITH_ID\", {\n  method: 'DELETE',\n  credentials: 'same-origin',\n  headers: { 'x-csrf-token': csrfToken },\n})\nif (!response.ok) throw new Error(`请求失败：${response.status}`)\nconst result = await response.json()"
          },
          {
            "lang": "shell",
            "label": "curl（网站会话）",
            "source": "# 使用网站当前会话；先完成 api-token 二次验证，再提供匹配的 CSRF。\ncurl --fail-with-body --request DELETE 'http://localhost:3001/api/webhooks/endpoints/REPLACE_WITH_ID' \\\n  --header \"Cookie: $NEXUSMC_COOKIE\" \\\n  --header \"x-csrf-token: $NEXUSMC_CSRF_TOKEN\""
          }
        ]
      }
    },
    "/api/webhooks/endpoints/{id}/rotate-secret": {
      "post": {
        "operationId": "rotateWebhookSecret",
        "summary": "轮换 Webhook 签名密钥",
        "tags": [
          "Webhook 管理"
        ],
        "description": "要求 Cookie、CSRF、owner 与 api-token 强验证。轮换立即推进版本并取消旧代未完成投递，没有双密钥重叠期；新 signingSecret 只显示一次。",
        "security": [
          {
            "websiteSession": [],
            "csrfHeader": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1
            },
            "example": "example-id"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "required": [],
                "additionalProperties": false
              },
              "example": {}
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功；无额外 data 信封。",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "endpoint": {
                      "$ref": "#/components/schemas/WebhookEndpoint"
                    },
                    "signingSecret": {
                      "type": "string",
                      "description": "仅创建或轮换时显示一次；作为 UTF-8 字符串保存到接收端私密环境，不是 OAuth client secret。"
                    }
                  },
                  "required": [
                    "endpoint",
                    "signingSecret"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "endpoint": {
                    "id": "example-value",
                    "name": "example-value",
                    "url": "https://receiver.example.com/webhooks/nexusmc",
                    "clientId": null,
                    "enabled": true,
                    "reviewStatus": "pending",
                    "reviewedAt": null,
                    "reviewNote": "example-value",
                    "version": "1",
                    "createdAt": "2026-10-16T00:00:00.000Z",
                    "updatedAt": "2026-10-16T00:00:00.000Z"
                  },
                  "signingSecret": "example-value"
                }
              }
            }
          },
          "400": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 400,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          },
          "401": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 401,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          },
          "403": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 403,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          },
          "404": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 404,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          },
          "429": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 429,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          },
          "503": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 503,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          }
        },
        "x-required-proof": "api-token",
        "x-proof-ttl-seconds": 300,
        "x-codeSamples": [
          {
            "lang": "javascript",
            "label": "Fetch（网站同源）",
            "source": "// 在网站同源页面执行，Cookie 由浏览器自动附带。请先在网站完成 api-token 二次验证。\nconst csrfToken = decodeURIComponent(document.cookie.split(';').map(value => value.trim()).find(value => value.startsWith('csrf_token='))?.slice('csrf_token='.length) ?? '')\nif (!csrfToken) throw new Error('请先在网站登录')\nconst response = await fetch(\"/api/webhooks/endpoints/REPLACE_WITH_ID/rotate-secret\", {\n  method: 'POST',\n  credentials: 'same-origin',\n  headers: { 'x-csrf-token': csrfToken, 'Content-Type': 'application/json' },\n  body: JSON.stringify({}),\n})\nif (!response.ok) throw new Error(`请求失败：${response.status}`)\nconst result = await response.json()"
          },
          {
            "lang": "shell",
            "label": "curl（网站会话）",
            "source": "# 使用网站当前会话；先完成 api-token 二次验证，再提供匹配的 CSRF。\ncurl --fail-with-body --request POST 'http://localhost:3001/api/webhooks/endpoints/REPLACE_WITH_ID/rotate-secret' \\\n  --header \"Cookie: $NEXUSMC_COOKIE\" \\\n  --header \"x-csrf-token: $NEXUSMC_CSRF_TOKEN\" \\\n  --header 'Content-Type: application/json' \\\n  --data '{}'"
          }
        ]
      }
    },
    "/api/webhooks/endpoints/{id}/subscriptions": {
      "get": {
        "operationId": "listWebhookSubscriptions",
        "summary": "列出端点订阅",
        "tags": [
          "Webhook 管理"
        ],
        "description": "只接受当前网站 Cookie 会话并检查 owner。PAT/OAuth access 不可调用。",
        "security": [
          {
            "websiteSession": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1
            },
            "example": "example-id"
          }
        ],
        "responses": {
          "200": {
            "description": "成功；无额外 data 信封。",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/WebhookSubscription"
                      }
                    },
                    "quota": {
                      "const": 100
                    }
                  },
                  "required": [
                    "items",
                    "quota"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "items": [],
                  "quota": 100
                }
              }
            }
          },
          "400": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 400,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          },
          "401": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 401,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          },
          "403": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 403,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          },
          "404": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 404,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          },
          "429": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 429,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          },
          "503": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 503,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "javascript",
            "label": "Fetch（网站同源）",
            "source": "// 在网站同源页面执行，Cookie 由浏览器自动附带。\nconst response = await fetch(\"/api/webhooks/endpoints/REPLACE_WITH_ID/subscriptions\", {\n  method: 'GET',\n  credentials: 'same-origin',\n})\nif (!response.ok) throw new Error(`请求失败：${response.status}`)\nconst result = await response.json()"
          },
          {
            "lang": "shell",
            "label": "curl（网站会话）",
            "source": "# 使用网站当前会话；不要填写 PAT/OAuth token。\ncurl --fail-with-body --request GET 'http://localhost:3001/api/webhooks/endpoints/REPLACE_WITH_ID/subscriptions' \\\n  --header \"Cookie: $NEXUSMC_COOKIE\""
          }
        ]
      },
      "post": {
        "operationId": "createWebhookSubscription",
        "summary": "订阅资源发布或知识库更新",
        "tags": [
          "Webhook 管理"
        ],
        "description": "要求 Cookie、CSRF、owner 与 api-token 强验证。已审核端点必须启用，目标当前公开；资源与知识库合计最多 100 个订阅。省略 targetKind 保留资源协议：维度内 OR、跨维度 AND，加载器和版本匹配同一物理发布。知识库独立流不接受发布筛选。新订阅从锁定的当前序号之后开始；改地址、轮换密钥、停用/启用及应用撤权均取消旧任务并推进两种订阅边界。",
        "security": [
          {
            "websiteSession": [],
            "csrfHeader": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1
            },
            "example": "example-id"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "targetKind": {
                        "const": "resource"
                      },
                      "resourceSlug": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 200
                      },
                      "events": {
                        "type": "array",
                        "maxItems": 100,
                        "minItems": 1,
                        "items": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 100,
                          "enum": [
                            "release.published",
                            "release.updated",
                            "release.withdrawn"
                          ]
                        },
                        "default": [
                          "release.published",
                          "release.updated",
                          "release.withdrawn"
                        ]
                      },
                      "loaders": {
                        "type": "array",
                        "maxItems": 100,
                        "items": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 100
                        },
                        "default": []
                      },
                      "mcVersions": {
                        "type": "array",
                        "maxItems": 100,
                        "items": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 100
                        },
                        "default": []
                      },
                      "releaseTypes": {
                        "type": "array",
                        "maxItems": 100,
                        "minItems": 1,
                        "items": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 100,
                          "enum": [
                            "release",
                            "beta",
                            "alpha"
                          ]
                        },
                        "default": [
                          "release"
                        ]
                      }
                    },
                    "required": [
                      "resourceSlug"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "targetKind": {
                        "const": "knowledge_base"
                      },
                      "knowledgeBaseSlug": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 200
                      },
                      "events": {
                        "type": "array",
                        "maxItems": 100,
                        "minItems": 1,
                        "items": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 100,
                          "enum": [
                            "knowledge.published",
                            "knowledge.updated",
                            "knowledge.page.published",
                            "knowledge.page.updated",
                            "knowledge.page.withdrawn",
                            "knowledge.withdrawn",
                            "knowledge.archived",
                            "knowledge.restored"
                          ]
                        },
                        "default": [
                          "knowledge.published",
                          "knowledge.updated",
                          "knowledge.page.published",
                          "knowledge.page.updated",
                          "knowledge.page.withdrawn",
                          "knowledge.withdrawn",
                          "knowledge.archived",
                          "knowledge.restored"
                        ]
                      }
                    },
                    "required": [
                      "targetKind",
                      "knowledgeBaseSlug"
                    ],
                    "additionalProperties": false
                  }
                ]
              },
              "example": {
                "resourceSlug": "example-value"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功；无额外 data 信封。",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "subscription": {
                      "$ref": "#/components/schemas/WebhookSubscription"
                    }
                  },
                  "required": [
                    "subscription"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "subscription": {
                    "id": "example-value",
                    "resourceId": "example-value",
                    "resourceSlug": null,
                    "events": [],
                    "loaders": [],
                    "mcVersions": [],
                    "releaseTypes": [],
                    "createdAt": "2026-10-16T00:00:00.000Z"
                  }
                }
              }
            }
          },
          "400": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 400,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          },
          "401": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 401,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          },
          "403": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 403,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          },
          "404": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 404,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          },
          "429": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 429,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          },
          "503": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 503,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          }
        },
        "x-required-proof": "api-token",
        "x-proof-ttl-seconds": 300,
        "x-codeSamples": [
          {
            "lang": "javascript",
            "label": "Fetch（网站同源）",
            "source": "// 在网站同源页面执行，Cookie 由浏览器自动附带。请先在网站完成 api-token 二次验证。\nconst csrfToken = decodeURIComponent(document.cookie.split(';').map(value => value.trim()).find(value => value.startsWith('csrf_token='))?.slice('csrf_token='.length) ?? '')\nif (!csrfToken) throw new Error('请先在网站登录')\nconst response = await fetch(\"/api/webhooks/endpoints/REPLACE_WITH_ID/subscriptions\", {\n  method: 'POST',\n  credentials: 'same-origin',\n  headers: { 'x-csrf-token': csrfToken, 'Content-Type': 'application/json' },\n  body: JSON.stringify({\"resourceSlug\":\"example-value\"}),\n})\nif (!response.ok) throw new Error(`请求失败：${response.status}`)\nconst result = await response.json()"
          },
          {
            "lang": "shell",
            "label": "curl（网站会话）",
            "source": "# 使用网站当前会话；先完成 api-token 二次验证，再提供匹配的 CSRF。\ncurl --fail-with-body --request POST 'http://localhost:3001/api/webhooks/endpoints/REPLACE_WITH_ID/subscriptions' \\\n  --header \"Cookie: $NEXUSMC_COOKIE\" \\\n  --header \"x-csrf-token: $NEXUSMC_CSRF_TOKEN\" \\\n  --header 'Content-Type: application/json' \\\n  --data '{\"resourceSlug\":\"example-value\"}'"
          }
        ]
      }
    },
    "/api/webhooks/endpoints/{id}/subscriptions/{subscriptionId}": {
      "delete": {
        "operationId": "deleteWebhookSubscription",
        "summary": "删除资源订阅",
        "tags": [
          "Webhook 管理"
        ],
        "description": "只接受当前网站 Cookie 会话；须为 owner，并持有匹配 Cookie 的 x-csrf-token 及当前会话用途 api-token 的二次验证（300 秒）。Origin/Fetch Metadata 和锁后期限复核仍生效。PAT/OAuth access 不可调用。",
        "security": [
          {
            "websiteSession": [],
            "csrfHeader": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1
            },
            "example": "example-id"
          },
          {
            "name": "subscriptionId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1
            },
            "example": "example-id"
          }
        ],
        "responses": {
          "200": {
            "description": "成功；无额外 data 信封。",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "const": true
                    }
                  },
                  "required": [
                    "success"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true
                }
              }
            }
          },
          "400": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 400,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          },
          "401": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 401,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          },
          "403": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 403,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          },
          "404": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 404,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          },
          "429": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 429,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          },
          "503": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 503,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          }
        },
        "x-required-proof": "api-token",
        "x-proof-ttl-seconds": 300,
        "x-codeSamples": [
          {
            "lang": "javascript",
            "label": "Fetch（网站同源）",
            "source": "// 在网站同源页面执行，Cookie 由浏览器自动附带。请先在网站完成 api-token 二次验证。\nconst csrfToken = decodeURIComponent(document.cookie.split(';').map(value => value.trim()).find(value => value.startsWith('csrf_token='))?.slice('csrf_token='.length) ?? '')\nif (!csrfToken) throw new Error('请先在网站登录')\nconst response = await fetch(\"/api/webhooks/endpoints/REPLACE_WITH_ID/subscriptions/REPLACE_WITH_SUBSCRIPTIONID\", {\n  method: 'DELETE',\n  credentials: 'same-origin',\n  headers: { 'x-csrf-token': csrfToken },\n})\nif (!response.ok) throw new Error(`请求失败：${response.status}`)\nconst result = await response.json()"
          },
          {
            "lang": "shell",
            "label": "curl（网站会话）",
            "source": "# 使用网站当前会话；先完成 api-token 二次验证，再提供匹配的 CSRF。\ncurl --fail-with-body --request DELETE 'http://localhost:3001/api/webhooks/endpoints/REPLACE_WITH_ID/subscriptions/REPLACE_WITH_SUBSCRIPTIONID' \\\n  --header \"Cookie: $NEXUSMC_COOKIE\" \\\n  --header \"x-csrf-token: $NEXUSMC_CSRF_TOKEN\""
          }
        ]
      }
    },
    "/api/webhooks/endpoints/{id}/deliveries": {
      "get": {
        "operationId": "listWebhookDeliveries",
        "summary": "查看投递记录",
        "tags": [
          "Webhook 管理"
        ],
        "description": "只接受当前网站 Cookie 会话并检查 owner。PAT/OAuth access 不可调用。",
        "security": [
          {
            "websiteSession": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1
            },
            "example": "example-id"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 1000
            },
            "description": "原样传回上页 nextCursor，不解析或构造。"
          }
        ],
        "responses": {
          "200": {
            "description": "成功；无额外 data 信封。",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/WebhookDelivery"
                      }
                    },
                    "hasMore": {
                      "type": "boolean"
                    },
                    "nextCursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  },
                  "required": [
                    "items",
                    "hasMore",
                    "nextCursor"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "items": [],
                  "hasMore": true,
                  "nextCursor": null
                }
              }
            }
          },
          "400": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 400,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          },
          "401": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 401,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          },
          "403": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 403,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          },
          "404": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 404,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          },
          "429": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 429,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          },
          "503": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 503,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "javascript",
            "label": "Fetch（网站同源）",
            "source": "// 在网站同源页面执行，Cookie 由浏览器自动附带。\nconst response = await fetch(\"/api/webhooks/endpoints/REPLACE_WITH_ID/deliveries\", {\n  method: 'GET',\n  credentials: 'same-origin',\n})\nif (!response.ok) throw new Error(`请求失败：${response.status}`)\nconst result = await response.json()"
          },
          {
            "lang": "shell",
            "label": "curl（网站会话）",
            "source": "# 使用网站当前会话；不要填写 PAT/OAuth token。\ncurl --fail-with-body --request GET 'http://localhost:3001/api/webhooks/endpoints/REPLACE_WITH_ID/deliveries' \\\n  --header \"Cookie: $NEXUSMC_COOKIE\""
          }
        ]
      }
    },
    "/api/webhooks/endpoints/{id}/deliveries/{deliveryId}/retry": {
      "post": {
        "operationId": "retryWebhookDelivery",
        "summary": "重试当前版本的失败投递",
        "tags": [
          "Webhook 管理"
        ],
        "description": "要求 Cookie、CSRF、owner 与 api-token 强验证。仅当前端点版本的 failed 可重置为 pending；端点/应用/订阅及普通事件的当前公开代次均须有效。成功表示重置待发送，不表示接收端已接收。",
        "security": [
          {
            "websiteSession": [],
            "csrfHeader": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1
            },
            "example": "example-id"
          },
          {
            "name": "deliveryId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1
            },
            "example": "example-id"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "required": [],
                "additionalProperties": false
              },
              "example": {}
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功；无额外 data 信封。",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "const": true
                    }
                  },
                  "required": [
                    "success"
                  ],
                  "additionalProperties": false
                },
                "example": {
                  "success": true
                }
              }
            }
          },
          "400": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 400,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          },
          "401": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 401,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          },
          "403": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 403,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          },
          "404": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 404,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          },
          "429": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 429,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          },
          "503": {
            "description": "请求、会话、配额、owner 或依赖检查失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookManagementError"
                },
                "example": {
                  "statusCode": 503,
                  "statusMessage": "请求未能完成",
                  "data": {
                    "code": "REQUEST_FAILED",
                    "message": "请核对参数、会话或稍后重试。"
                  }
                }
              }
            }
          }
        },
        "x-required-proof": "api-token",
        "x-proof-ttl-seconds": 300,
        "x-codeSamples": [
          {
            "lang": "javascript",
            "label": "Fetch（网站同源）",
            "source": "// 在网站同源页面执行，Cookie 由浏览器自动附带。请先在网站完成 api-token 二次验证。\nconst csrfToken = decodeURIComponent(document.cookie.split(';').map(value => value.trim()).find(value => value.startsWith('csrf_token='))?.slice('csrf_token='.length) ?? '')\nif (!csrfToken) throw new Error('请先在网站登录')\nconst response = await fetch(\"/api/webhooks/endpoints/REPLACE_WITH_ID/deliveries/REPLACE_WITH_DELIVERYID/retry\", {\n  method: 'POST',\n  credentials: 'same-origin',\n  headers: { 'x-csrf-token': csrfToken, 'Content-Type': 'application/json' },\n  body: JSON.stringify({}),\n})\nif (!response.ok) throw new Error(`请求失败：${response.status}`)\nconst result = await response.json()"
          },
          {
            "lang": "shell",
            "label": "curl（网站会话）",
            "source": "# 使用网站当前会话；先完成 api-token 二次验证，再提供匹配的 CSRF。\ncurl --fail-with-body --request POST 'http://localhost:3001/api/webhooks/endpoints/REPLACE_WITH_ID/deliveries/REPLACE_WITH_DELIVERYID/retry' \\\n  --header \"Cookie: $NEXUSMC_COOKIE\" \\\n  --header \"x-csrf-token: $NEXUSMC_CSRF_TOKEN\" \\\n  --header 'Content-Type: application/json' \\\n  --data '{}'"
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "WebhookEndpoint": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "clientId": {
            "type": [
              "string",
              "null"
            ]
          },
          "enabled": {
            "type": "boolean"
          },
          "reviewStatus": {
            "type": "string",
            "enum": [
              "pending",
              "approved",
              "rejected"
            ]
          },
          "reviewedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "reviewNote": {
            "type": "string"
          },
          "version": {
            "type": "string",
            "pattern": "^[0-9]+$"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "name",
          "url",
          "clientId",
          "enabled",
          "reviewStatus",
          "reviewedAt",
          "reviewNote",
          "version",
          "createdAt",
          "updatedAt"
        ],
        "additionalProperties": false
      },
      "WebhookResourceSubscription": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "resourceId": {
            "type": "string"
          },
          "resourceSlug": {
            "type": [
              "string",
              "null"
            ]
          },
          "events": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "release.published",
                "release.updated",
                "release.withdrawn"
              ]
            }
          },
          "loaders": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "mcVersions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "releaseTypes": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "release",
                "beta",
                "alpha"
              ]
            }
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "resourceId",
          "resourceSlug",
          "events",
          "loaders",
          "mcVersions",
          "releaseTypes",
          "createdAt"
        ],
        "additionalProperties": false
      },
      "WebhookKnowledgeSubscription": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "targetKind": {
            "const": "knowledge_base"
          },
          "knowledgeBaseId": {
            "type": "string"
          },
          "knowledgeBaseSlug": {
            "type": [
              "string",
              "null"
            ]
          },
          "events": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "knowledge.published",
                "knowledge.updated",
                "knowledge.page.published",
                "knowledge.page.updated",
                "knowledge.page.withdrawn",
                "knowledge.withdrawn",
                "knowledge.archived",
                "knowledge.restored"
              ]
            }
          },
          "loaders": {
            "type": "array",
            "maxItems": 0,
            "items": {
              "type": "string"
            }
          },
          "mcVersions": {
            "type": "array",
            "maxItems": 0,
            "items": {
              "type": "string"
            }
          },
          "releaseTypes": {
            "type": "array",
            "maxItems": 0,
            "items": {
              "type": "string"
            }
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "targetKind",
          "knowledgeBaseId",
          "knowledgeBaseSlug",
          "events",
          "loaders",
          "mcVersions",
          "releaseTypes",
          "createdAt"
        ],
        "additionalProperties": false
      },
      "WebhookSubscription": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/WebhookResourceSubscription"
          },
          {
            "$ref": "#/components/schemas/WebhookKnowledgeSubscription"
          }
        ]
      },
      "WebhookDelivery": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "eventId": {
            "type": "string"
          },
          "eventType": {
            "type": "string",
            "enum": [
              "release.published",
              "release.updated",
              "release.withdrawn",
              "knowledge.published",
              "knowledge.updated",
              "knowledge.page.published",
              "knowledge.page.updated",
              "knowledge.page.withdrawn",
              "knowledge.withdrawn",
              "knowledge.archived",
              "knowledge.restored"
            ]
          },
          "releaseId": {
            "type": [
              "string",
              "null"
            ]
          },
          "resourceId": {
            "type": [
              "string",
              "null"
            ]
          },
          "targetKind": {
            "const": "knowledge_base"
          },
          "knowledgeBaseId": {
            "type": "string"
          },
          "pageId": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "sending",
              "succeeded",
              "failed",
              "cancelled"
            ]
          },
          "attempts": {
            "type": "integer",
            "minimum": 0
          },
          "httpStatus": {
            "type": [
              "integer",
              "null"
            ]
          },
          "lastError": {
            "type": [
              "string",
              "null"
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "availableAt": {
            "type": "string",
            "format": "date-time"
          },
          "finishedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "eventId",
          "eventType",
          "releaseId",
          "resourceId",
          "status",
          "attempts",
          "httpStatus",
          "lastError",
          "createdAt",
          "availableAt",
          "finishedAt"
        ],
        "additionalProperties": false
      },
      "WebhookManagementError": {
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "statusCode": {
                "type": "integer"
              },
              "statusMessage": {
                "type": "string"
              },
              "data": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  }
                },
                "required": [
                  "code",
                  "message"
                ],
                "additionalProperties": true
              }
            },
            "required": [
              "statusCode",
              "statusMessage",
              "data"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "ok": {
                "const": false
              },
              "error": {
                "type": "string"
              }
            },
            "required": [
              "ok",
              "error"
            ],
            "additionalProperties": false
          }
        ]
      },
      "WebhookPublished": {
        "type": "object",
        "properties": {
          "schemaVersion": {
            "const": 1
          },
          "id": {
            "type": "string"
          },
          "sequence": {
            "type": "string",
            "pattern": "^[0-9]+$"
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time"
          },
          "type": {
            "type": "string",
            "enum": [
              "release.published",
              "release.updated"
            ]
          },
          "resource": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "slug": {
                "type": "string"
              },
              "title": {
                "type": "string"
              }
            },
            "required": [
              "id",
              "slug",
              "title"
            ],
            "additionalProperties": false
          },
          "release": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "batchId": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "versionNumber": {
                "type": "string"
              },
              "name": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "releaseType": {
                "type": "string",
                "enum": [
                  "release",
                  "beta",
                  "alpha"
                ]
              },
              "publishedAt": {
                "type": "string",
                "format": "date-time"
              },
              "loaders": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "mcVersions": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            },
            "required": [
              "id",
              "batchId",
              "versionNumber",
              "name",
              "releaseType",
              "publishedAt",
              "loaders",
              "mcVersions"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "schemaVersion",
          "id",
          "sequence",
          "occurredAt",
          "type",
          "resource",
          "release"
        ],
        "additionalProperties": false
      },
      "WebhookWithdrawn": {
        "type": "object",
        "properties": {
          "schemaVersion": {
            "const": 1
          },
          "id": {
            "type": "string"
          },
          "sequence": {
            "type": "string",
            "pattern": "^[0-9]+$"
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time"
          },
          "type": {
            "const": "release.withdrawn"
          },
          "resource": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              }
            },
            "required": [
              "id"
            ],
            "additionalProperties": false
          },
          "release": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              }
            },
            "required": [
              "id"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "schemaVersion",
          "id",
          "sequence",
          "occurredAt",
          "type",
          "resource",
          "release"
        ],
        "additionalProperties": false
      },
      "WebhookEvent": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/WebhookPublished"
          },
          {
            "$ref": "#/components/schemas/WebhookWithdrawn"
          }
        ]
      },
      "KnowledgeWebhookPublic": {
        "type": "object",
        "properties": {
          "schemaVersion": {
            "const": 1
          },
          "id": {
            "type": "string"
          },
          "sequence": {
            "type": "string",
            "pattern": "^[0-9]+$"
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time"
          },
          "revision": {
            "type": "string",
            "pattern": "^[0-9]+$"
          },
          "changeKind": {
            "type": "string",
            "enum": [
              "publication",
              "information",
              "structure",
              "page",
              "status"
            ]
          },
          "type": {
            "type": "string",
            "enum": [
              "knowledge.published",
              "knowledge.updated",
              "knowledge.archived",
              "knowledge.restored"
            ]
          },
          "knowledgeBase": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "slug": {
                "type": "string"
              },
              "title": {
                "type": "string"
              },
              "canonicalPath": {
                "type": "string"
              }
            },
            "required": [
              "id",
              "slug",
              "title",
              "canonicalPath"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "schemaVersion",
          "id",
          "sequence",
          "occurredAt",
          "revision",
          "changeKind",
          "type",
          "knowledgeBase"
        ],
        "additionalProperties": false
      },
      "KnowledgeWebhookPage": {
        "type": "object",
        "properties": {
          "schemaVersion": {
            "const": 1
          },
          "id": {
            "type": "string"
          },
          "sequence": {
            "type": "string",
            "pattern": "^[0-9]+$"
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time"
          },
          "revision": {
            "type": "string",
            "pattern": "^[0-9]+$"
          },
          "changeKind": {
            "type": "string",
            "enum": [
              "publication",
              "information",
              "structure",
              "page",
              "status"
            ]
          },
          "type": {
            "type": "string",
            "enum": [
              "knowledge.page.published",
              "knowledge.page.updated"
            ]
          },
          "knowledgeBase": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "slug": {
                "type": "string"
              },
              "title": {
                "type": "string"
              },
              "canonicalPath": {
                "type": "string"
              }
            },
            "required": [
              "id",
              "slug",
              "title",
              "canonicalPath"
            ],
            "additionalProperties": false
          },
          "page": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "title": {
                "type": "string"
              },
              "canonicalPath": {
                "type": "string"
              },
              "revision": {
                "type": "string",
                "pattern": "^[0-9]+$"
              }
            },
            "required": [
              "id",
              "title",
              "canonicalPath",
              "revision"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "schemaVersion",
          "id",
          "sequence",
          "occurredAt",
          "revision",
          "changeKind",
          "type",
          "knowledgeBase",
          "page"
        ],
        "additionalProperties": false
      },
      "KnowledgeWebhookWithdrawn": {
        "type": "object",
        "properties": {
          "schemaVersion": {
            "const": 1
          },
          "id": {
            "type": "string"
          },
          "sequence": {
            "type": "string",
            "pattern": "^[0-9]+$"
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time"
          },
          "revision": {
            "type": "string",
            "pattern": "^[0-9]+$"
          },
          "changeKind": {
            "type": "string",
            "enum": [
              "publication",
              "information",
              "structure",
              "page",
              "status"
            ]
          },
          "type": {
            "const": "knowledge.withdrawn"
          },
          "knowledgeBase": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              }
            },
            "required": [
              "id"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "schemaVersion",
          "id",
          "sequence",
          "occurredAt",
          "revision",
          "changeKind",
          "type",
          "knowledgeBase"
        ],
        "additionalProperties": false
      },
      "KnowledgeWebhookPageWithdrawn": {
        "type": "object",
        "properties": {
          "schemaVersion": {
            "const": 1
          },
          "id": {
            "type": "string"
          },
          "sequence": {
            "type": "string",
            "pattern": "^[0-9]+$"
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time"
          },
          "revision": {
            "type": "string",
            "pattern": "^[0-9]+$"
          },
          "changeKind": {
            "type": "string",
            "enum": [
              "publication",
              "information",
              "structure",
              "page",
              "status"
            ]
          },
          "type": {
            "const": "knowledge.page.withdrawn"
          },
          "knowledgeBase": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              }
            },
            "required": [
              "id"
            ],
            "additionalProperties": false
          },
          "page": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              }
            },
            "required": [
              "id"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "schemaVersion",
          "id",
          "sequence",
          "occurredAt",
          "revision",
          "changeKind",
          "type",
          "knowledgeBase",
          "page"
        ],
        "additionalProperties": false
      },
      "KnowledgeWebhookEvent": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/KnowledgeWebhookPublic"
          },
          {
            "$ref": "#/components/schemas/KnowledgeWebhookPage"
          },
          {
            "$ref": "#/components/schemas/KnowledgeWebhookWithdrawn"
          },
          {
            "$ref": "#/components/schemas/KnowledgeWebhookPageWithdrawn"
          }
        ]
      }
    },
    "securitySchemes": {
      "websiteSession": {
        "type": "apiKey",
        "in": "cookie",
        "name": "access_token",
        "description": "当前网站 HttpOnly 会话 Cookie；不在文档中预填。"
      },
      "csrfHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "x-csrf-token",
        "description": "必须匹配同一浏览器会话的 csrf_token Cookie；不能替代 api-token 强验证。"
      }
    }
  },
  "webhooks": {
    "knowledgeUpdate": {
      "post": {
        "operationId": "receiveKnowledgeUpdateEvent",
        "summary": "接收知识库公开更新",
        "description": "仅通知已推广的公开事实。首批只发一次，私稿和纯阅读模板变化不发。稳定事件 ID 用于去重，序号为按库十进制字符串；恢复产生新可见性代次，不重放旧公开载荷。撤回事件只含目标 ID 和状态。签名、HTTPS 限制、10 秒期限、8 次有界重试和至少一次语义与资源事件相同。",
        "parameters": [
          {
            "name": "webhook-id",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "webhook-timestamp",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "webhook-signature",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/KnowledgeWebhookEvent"
              }
            }
          }
        },
        "responses": {
          "204": {
            "description": "已持久接受"
          },
          "503": {
            "description": "暂时失败，允许退避重试"
          }
        }
      }
    },
    "resourceRelease": {
      "post": {
        "operationId": "receiveResourceReleaseEvent",
        "summary": "接收资源发布事件",
        "description": "接收地址由用户登记，平台 POST 原始 JSON，最多 256 KiB，10 秒有界 HTTPS，无重定向；接收端对 eventId.timestamp.rawBody 计算 HMAC-SHA256，使用 signingSecret 的原始 UTF-8 字节，签名为 v1,<base64>。先验原始字节再解析 JSON；按稳定事件 ID 持久去重与入队，至少一次投递。withdrawn 只含 ID 墓碑，不披露旧标题或文件。",
        "parameters": [
          {
            "name": "webhook-id",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "webhook-timestamp",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[0-9]+$"
            }
          },
          {
            "name": "webhook-signature",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^v1,[A-Za-z0-9+/]+={0,2}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookEvent"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "其他 2xx 同样表示本次尝试成功；响应正文最多 64 KiB。"
          },
          "204": {
            "description": "原始事件已持久接受；请尽快返回，不同步运行重任务。"
          },
          "503": {
            "description": "暂时无法接受，应失败以便平台按退避策略重试。"
          }
        }
      }
    }
  }
}
