API 参考

Webhook 端点

获取 Webhook 端点

返回单个 Webhook 端点的配置。

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

调用前准备

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

请求参数

请求头

X-Api-Key
string必填

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

路径参数

endpoint_id
string必填

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

请求体

该接口无需 JSON 请求体。

如何理解结果

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

响应 200 OK

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "id": "we_example",
    "url": "https://example.com/webhook",
    "status": "active",
    "subscribed_events": [
      "message.received"
    ],
    "signing_enabled": true,
    "retry_policy": {
      "max_attempts": 3
    }
  }
}

响应体

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

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

401

未授权

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

500

服务端错误

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

失败后怎么处理

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

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