API 参考

Webhook 端点

删除 Webhook 端点

删除一个 Webhook 端点。删除成功不返回响应体。

DELETEhttps://api.unifyport.ai/v1/webhook-endpoints/{endpoint_id}

支持的渠道

all

调用前准备

在服务端使用资源所属工作区的 X-Api-Key。运行示例前替换所有占位符。

参数从哪里取得
account_id
从创建或查询账号的响应取得 data.id。账号标识属于 X-Api-Key 对应的工作区。 获取账号

请求参数

请求头

X-Api-Key
string必填

工作区 API Key,工作区由该请求头解析得到。

路径参数

endpoint_id
string必填

用于该 webhook endpoints 路由的标识符。

查询参数

account_id
string

可选的公开账号 ID,例如 acc_example。不可为空、仅含空白或重复出现。参数名必须精确使用 account_id;大小写变体返回 400 invalid_request,不按省略处理。列表省略时只返回工作空间端点;指定时只返回账号独立配置(没有独立配置则 data=[],不混入继承的工作空间配置)。详情、停用、删除仅校验已有账号归属;不匹配返回 400 invalid_request。显式账号不存在或不属于当前工作空间返回 404 account_not_found (20020)。

minLength: 1 · pattern: \S

请求体

该接口无需 JSON 请求体。

如何理解结果

204 表示端点已删除,没有响应体;排查时保留 X-Request-Id。删除后不再通过该端点接收新投递,但不保证取消已经在途的请求。

响应 204 No Content

无响应体。

响应

204

204 No Content

请求成功,无响应体。

400

请求错误

请求体、路径或参数不合法。

401

未授权

X-Api-Key 请求头缺失或无效。

403

禁止访问

请求已识别,但不允许执行该操作。

404

未找到

未找到请求的资源;请结合 error.code 和当前操作核对。

500

服务端错误

服务端遇到了未预期的错误。

失败后怎么处理

检查 HTTP 状态和 error.code/numeric_code,保存 request_id 用于排查。按原因修正参数、继续授权或检查运行态。重试发送及其他写操作前先确认上一次结果,避免重复操作。 错误码参考

结合当前操作读取 HTTP 状态、error.code 和 error.numeric_code。数字码按字符串处理。保留 request_id 排障;它不是幂等键或任务标识。

invalid_request · 10000 · 400

检查 JSON 请求体和必填字段。

处理与重试: 按当前操作与渠道条件修正参数后再请求。重复提交相同的无效请求不会解决错误。

示意 JSON;message 随实际原因变化 · 400 · 10000
{
  "request_id": "req_example",
  "error": {
    "code": "invalid_request",
    "numeric_code": "10000",
    "message": "Invalid request parameters"
  }
}
invalid_target_workspace · 11003 · 400

工作区覆盖目标为空或格式无效。移除覆盖请求头,改用目标工作区所属的 API Key。

触发条件: 适用于携带 X-Workspace-Id 工作区覆盖请求头的请求。

处理与重试: 按当前操作与渠道条件修正参数后再请求。重复提交相同的无效请求不会解决错误。

示意 JSON;message 随实际原因变化 · 400 · 11003
{
  "request_id": "req_example",
  "error": {
    "code": "invalid_target_workspace",
    "numeric_code": "11003",
    "message": "Invalid target workspace"
  }
}
invalid_api_key · 11001 · 401

检查 API Key 是否正确且已启用。

处理与重试: 保留 request_id 与结构化错误码,先排查当前操作,再决定下一步。

示意 JSON;message 随实际原因变化 · 401 · 11001
{
  "request_id": "req_example",
  "error": {
    "code": "invalid_api_key",
    "numeric_code": "11001",
    "message": "Invalid API key"
  }
}
missing_api_key · 11000 · 401

请添加 X-Api-Key 请求头。

处理与重试: 保留 request_id 与结构化错误码,先排查当前操作,再决定下一步。

示例 · 401 · 11000
{
  "request_id": "req_xxx",
  "error": {
    "code": "missing_api_key",
    "numeric_code": "11000",
    "message": "Missing X-Api-Key header"
  }
}
workspace_override_forbidden · 11002 · 403

请求尝试使用此 API Key 无权使用的工作区覆盖。移除覆盖请求头,改用目标工作区所属的 API Key。

触发条件: 适用于携带 X-Workspace-Id 工作区覆盖请求头的请求。

处理与重试: 保留 request_id 与结构化错误码,先排查当前操作,再决定下一步。

示意 JSON;message 随实际原因变化 · 403 · 11002
{
  "request_id": "req_example",
  "error": {
    "code": "workspace_override_forbidden",
    "numeric_code": "11002",
    "message": "Workspace override is not allowed"
  }
}
account_not_found · 20020 · 404

核对 account_id,并使用账号所属工作区的 X-Api-Key。此工作区下未找到的账号不能用当前 Key 访问。

处理与重试: 核对目标标识、资源归属与当前工作区。不要把已确认缺失或无法访问的目标当作临时服务故障自动重试。

示意 JSON;message 随实际原因变化 · 404 · 20020
{
  "request_id": "req_example",
  "error": {
    "code": "account_not_found",
    "numeric_code": "20020",
    "message": "Account not found"
  }
}
target_workspace_not_found · 11004 · 404

覆盖指定的工作区不存在或不可用。核对工作区归属,移除覆盖请求头并使用目标工作区 API Key;重复请求不会增加访问权限。

触发条件: 适用于携带 X-Workspace-Id 工作区覆盖请求头的请求。

处理与重试: 核对目标标识、资源归属与当前工作区。不要把已确认缺失或无法访问的目标当作临时服务故障自动重试。

示意 JSON;message 随实际原因变化 · 404 · 11004
{
  "request_id": "req_example",
  "error": {
    "code": "target_workspace_not_found",
    "numeric_code": "11004",
    "message": "Target workspace not found"
  }
}
delete_webhook_endpoint_failed · 40005 · 500

删除 Webhook 端点:无法确认本次删除结果。

处理与重试: 查询资源确认是否已删除,再决定是否需要再次删除。保留 request_id,按当前接口声明的成功响应处理。

示意 JSON;message 随实际原因变化 · 500 · 40005
{
  "request_id": "req_example",
  "error": {
    "code": "delete_webhook_endpoint_failed",
    "numeric_code": "40005",
    "message": "Failed to delete webhook endpoint"
  }
}