← API 参考
Webhook 端点POST

创建 Webhook 端点

创建 Webhook 接收端。url 必须是绝对 HTTP(S) URL，生产环境建议 HTTPS；status 仅可为 active / inactive。subscribed_events 接受公开标准事件名或 ["*"]；signing_secret 可选，retry_policy.max_attempts 默认 3，范围 0..5。

https://api.unifyport.ai/v1/webhook-endpoints

请求头

X-Api-Key
string必填

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

Content-Type
string必填

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

路径参数

该接口没有路径参数。

请求体

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 表示只投递首次请求。

响应体

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。

响应

201
201 Created

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

400
请求错误

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

401
未授权

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

请求

curl -X POST https://api.unifyport.ai/v1/webhook-endpoints \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/webhook",
  "status": "active",
  "subscribed_events": ["*"],
  "signing_secret": "<WEBHOOK_SIGNING_SECRET>"
}'

响应

{
  "data": {
    "id": "we_example",
    "url": "https://example.com/webhook",
    "status": "active",
    "subscribed_events": ["*"],
    "signing_enabled": true,
    "retry_policy": {
      "max_attempts": 3
    }
  }
}