§ API REFERENCE

创建 Webhook订阅

POST/webhook-endpointsscope: webhook:manage

创建 HTTPS出站订阅；signing_secret 只在本次响应返回一次。

鉴权：Authorization: Bearer <access_token>。写端点受限流保护。

§ 1

请求信息

REQUEST

POST https://api.lingxiguangnian.com/api/open/v1/webhook-endpoints

请求头

参数	类型	必填	说明
`Authorization`	string	是	Bearer <access_token>。由 POST /token 换取，有效期 2 小时；api_secret 不得直连业务端点（→ 401）。

请求体参数

参数	类型	必填	说明
`target_url`	https url	是	公网HTTPS地址；拒绝内网、回环、链路本地和云元数据地址。
`event_types`	string[]	是	execution.completed / execution.failed / report.generated / report.failed。
`description`	string	否	最多256字符。

§ 2

调用示例

EXAMPLES

POST /webhook-endpoints

curl -X POST "https://api.lingxiguangnian.com/api/open/v1/webhook-endpoints" -H "Authorization: Bearer oat_xxxxxxxxxxxxxxxx" -H "Content-Type: application/json" -d '{"target_url":"https://partner.example.com/webhooks/mbc","event_types":["report.generated"]}'

§ 3

返回结果

RESPONSE

返回字段

参数	类型	必填	说明
`id/target_url/event_types/status`	mixed	是	订阅投影。
`signing_secret`	string	是	whsec_前缀，明文仅返回一次。

RESPONSE · JSON

{ "success": true, "data": { "id": "11111111-1111-4111-8111-111111111111", "status": "ACTIVE", "signing_secret": "whsec_xxxxxxxxxxxxxxxx" } }

§ 4

端点错误码

ERRORS

通用鉴权、scope 与限流错误见「使用概述」；下表为本端点专属错误。

HTTP	error_code	触发条件
409	`open_api.webhook_subscription_conflict`	同一 APP 已有相同 target_url 的活跃订阅。
500	`open_api.webhook_write_failed`	Webhook订阅创建失败。

契约真源：apps/m-master/src/app/api/open/v1/webhook-endpoints/route.ts