API 参考

Webhook 端点

更新 Webhook 端点

更新 Webhook 端点。url 必须是绝对 HTTP(S) URL，生产环境建议 HTTPS；status 仅可为 active / inactive。subscribed_events 接受公开标准事件名或 ["*"]；空 signing_secret 关闭签名，max_attempts 范围 0..5。

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

调用前准备

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

PATCH 会替换 Webhook 配置。请提交所有需要保留的设置：省略 signing_secret 会关闭签名，省略 subscribed_events 会恢复接收全部公开事件，省略 retry_policy/max_attempts 会恢复默认重试 3 次。先读取现有配置，并提供自行保存的签名密钥。

请求参数

请求头

X-Api-Key
string必填

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

Content-Type
string必填

发送 JSON 请求体时使用 application/json。

路径参数

endpoint_id
string必填

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

请求体

url
string必填

接收 Webhook 的绝对 HTTP(S) URL；生产环境建议 HTTPS。

format: uri

status
string必填

端点状态：active 或 inactive。

enum: active, inactive

subscribed_events[]
string[]

推送到该端点的公开标准事件类型；使用 ["*"] 订阅全部公开事件，不包含 provider.raw_event。完整事件名参见标准事件类型与载荷。

signing_secret
string

可选的 Webhook 签名密钥，示例中请使用占位符。

retry_policy
object

可选重试策略。max_attempts 表示首次投递后的重试次数，默认 3，仅接受 0 到 5；0 表示只投递首次请求。

max_attempts
integer

首次投递后的重试次数，范围为 0 到 5；0 表示只投递首次请求。

如何理解结果

配置成功不代表事件已投递。触发相关事件，在接收端确认收到请求、验签通过并正确响应。

响应 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
    }
  }
}

响应体

id
string

Webhook 端点标识（we_...）。

url
string

接收 Webhook 投递的绝对 HTTP(S) URL；生产环境建议 HTTPS。

format: uri

status
string

端点状态：active 或 inactive。

enum: active, inactive

subscribed_events[]
string[]

投递到该端点的公开标准事件类型；["*"] 表示全部公开事件，不包含 provider.raw_event。

signing_enabled
boolean

设置了签名密钥且对投递进行签名时为 true。

retry_policy
object

接口返回的重试设置。max_attempts 统计首次投递后的重试次数，默认 3，范围为 0 到 5。

max_attempts
integer

已配置的首次投递后重试次数，范围为 0 到 5。

响应

200

200 OK

请求成功，响应体示例如上。

400

请求错误

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

401

未授权

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

失败后怎么处理

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

invalid_request · 10000 · 400
检查必填字段、格式和渠道条件，修正请求后再调用。
invalid_api_key · 11001 · 401
检查 X-Api-Key 是否正确、工作区是否有效。