Webhook 端点
停用 Webhook 端点
将 Webhook 端点状态设为 inactive,但不会删除端点。
https://api.unifyport.ai/v1/webhook-endpoints/{endpoint_id}/deactivate支持的渠道
调用前准备
在服务端使用资源所属工作区的 X-Api-Key。运行示例前替换所有占位符。
参数从哪里取得
- account_id
- 从创建或查询账号的响应取得 data.id。账号标识属于 X-Api-Key 对应的工作区。 获取账号
请求参数
请求头
X-Api-Key工作区 API Key,工作区由该请求头解析得到。
路径参数
endpoint_id用于该 webhook endpoints 路由的标识符。
查询参数
account_id可选的公开账号 ID,例如 acc_example。不可为空、仅含空白或重复出现。参数名必须精确使用 account_id;大小写变体返回 400 invalid_request,不按省略处理。列表省略时只返回工作空间端点;指定时只返回账号独立配置(没有独立配置则 data=[],不混入继承的工作空间配置)。详情、停用、删除仅校验已有账号归属;不匹配返回 400 invalid_request。显式账号不存在或不属于当前工作空间返回 404 account_not_found (20020)。
minLength: 1 · pattern: \S
请求体
该接口无需 JSON 请求体。
如何理解结果
确认响应中的 status=inactive。此端点不再用于新投递,但停用不保证取消已经在途的请求。
响应 200 OK
{
"request_id": "<REQUEST_ID>",
"data": {
"id": "we_example",
"url": "https://example.com/webhook-updated",
"status": "inactive",
"subscribed_events": [
"message.delivered",
"message.read"
],
"signing_enabled": false,
"retry_policy": {
"max_attempts": 1
}
}
}
响应体
idWebhook 端点标识(we_...)。
account_id账号独立端点的公开账号 ID;工作空间端点省略此字段,不返回 null。
minLength: 1
url接收 Webhook 投递的绝对 HTTP(S) URL;生产环境建议 HTTPS。
format: uri
status端点状态:active 或 inactive。
enum: active, inactive
subscribed_events[]投递到该端点的公开标准事件类型;["*"] 表示工作区可接收的公开事件,不包含 provider.raw_event。
signing_enabled设置了签名密钥且对投递进行签名时为 true。
retry_policyobject接口返回的重试设置。max_attempts 统计首次投递后的重试次数,默认 3,范围为 0 到 5。
retry_policy接口返回的重试设置。max_attempts 统计首次投递后的重试次数,默认 3,范围为 0 到 5。
max_attempts已配置的首次投递后重试次数,范围为 0 到 5。
响应
200200 OK
请求成功,响应体示例如上。
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" } }- deactivate_webhook_endpoint_failed · 40004 · 500
停用 Webhook 端点:无法确认停止或停用结果,恢复时应保留原本停止目标。
处理与重试: 查询当前状态,确认停止或停用是否已生效。不要为了恢复本次操作而启动或重连本来要停止的资源。
示意 JSON;message 随实际原因变化 · 500 · 40004
{ "request_id": "req_example", "error": { "code": "deactivate_webhook_endpoint_failed", "numeric_code": "40004", "message": "Failed to deactivate webhook endpoint" } }- deactivate_webhook_endpoint_failed · 40006 · 500
此归属范围内未找到目标 Webhook 端点。GET、PATCH 和停用保留各自操作 code 与 HTTP 500,数字原因是 40006。此细分不适用于幂等 DELETE;端点不存在时删除返回 204。
处理与重试: 核对目标标识、资源归属与当前工作区。不要把已确认缺失或无法访问的目标当作临时服务故障自动重试。
示意 JSON;message 随实际原因变化 · 500 · 40006
{ "request_id": "req_example", "error": { "code": "deactivate_webhook_endpoint_failed", "numeric_code": "40006", "message": "Webhook endpoint not found" } }