创建 Webhook

注册一个新的 Webhook 端点。响应中会包含每个 Webhook 独有的签名密钥 secret，仅返回这一次——请在响应离开你的代码之前妥善存储。

端点

POST /v1/webhooks

权重： 5 鉴权： 必须（已签名）——参见 鉴权。

请求体

名称	类型	必填	说明
url	string	YES	目标 URL。必须以 https:// 开头，且解析到一个公网可达、提供有效 TLS 证书的主机。普通的 http:// 和自签名证书会被拒绝。
events	array<string>	YES	要订阅的事件类型列表，不能为空。每个条目必须是 负载格式 中枚举的某个值，或者通配符 strategy.*、backtest.*、account.*、* 之一。
description	string	NO	自由格式的标签，长度 ≤ 200 字符。便于在仪表盘和列表响应中识别该 Webhook。
balance_low_threshold	string	NO	十进制字符串。仅当 events 包含 account.balance_low 时必填。当任一受跟踪资产的可用余额低于该值时触发 account.balance_low 事件。否则忽略。

响应

{
  "id": "wh_2a4f10",
  "url": "https://example.com/pipai-webhook",
  "events": ["strategy.deployed", "strategy.position_opened", "strategy.error", "backtest.job_done"],
  "description": "Production strategy alerts",
  "status": "active",
  "consecutive_failures": 0,
  "last_delivery_at": null,
  "last_success_at": null,
  "created_at": "2026-04-29T12:00:00Z",
  "secret": "k3mB2xQ9rFvT7nLpJhYwS4eUaC1oZ8dRgI6XbN0M",
  "_secret_warning": "Store this secret immediately — it will not be retrievable later."
}

响应字段

字段	类型	说明
id	string	Webhook 标识，格式为 wh_<6-8 hex>。
url	string	你提供的目标 URL。
events	array<string>	该 Webhook 订阅的事件类型列表。
description	string|null	提供的描述；如未提供则为 null。
status	enum	取值之一：active、paused、broken。新 Webhook 初始状态为 active。
consecutive_failures	integer	连续失败的投递次数。创建时始终为 0。
last_delivery_at	string|null	最近一次投递尝试的 ISO 8601 UTC 时间戳；若尚未投递任何事件则为 null。
last_success_at	string|null	最近一次成功投递（2xx）的 ISO 8601 UTC 时间戳；若无则为 null。
created_at	string	ISO 8601 UTC 创建时间。
secret	string	不透明的 base64url 字符串（约 40 字符），用于对该 Webhook 的每次投递进行签名。仅在创建时返回——后续读取不会包含该字段。请妥善存储。
_secret_warning	string	静态警告字符串，作为防御性提醒以促使你立刻保存 secret。

错误

• 400 INVALID_PARAMETER —— url 缺失、格式不正确，或使用了 http:// 而非 https://；events 为空或包含未知类型；description 超过 200 字符；balance_low_threshold 不是正的十进制数。
• 403 INSUFFICIENT_PERMISSION —— API 密钥缺少 webhooks:write 范围。
• 409 DUPLICATE_URL —— 该账户上已注册了具有相同 url 的 Webhook。
• 429 LIMIT_REACHED —— 该账户已有 25 个 Webhook（每账户上限）。请先删除一个已有 Webhook 再创建新的。

完整列表参见 错误。

示例

curl -X POST "https://api.pipai.example/v1/webhooks" \
  -H "X-PipAI-API-Key: $API_KEY" \
  -H "X-PipAI-Timestamp: $TS" \
  -H "X-PipAI-Signature: $SIG" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/pipai-webhook",
    "events": [
      "strategy.deployed",
      "strategy.position_opened",
      "strategy.error",
      "backtest.job_done"
    ],
    "description": "Production strategy alerts"
  }'