Webhook

Create Webhook

Create a Webhook endpoint and subscribe to events

POST

/api/v1/agentstudio/webhook_endpoints

cURL

curl --request POST \
  --url 'https://{workspace_id}.{region}.maas.aliyuncs.com/api/v1/agentstudio/webhook_endpoints' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "description": "生产环境会话事件",
  "url": "https://example.com/managedagent/webhooks",
  "events": [
    "session.updated",
    "session.status_idled",
    "session.thread_terminated"
  ]
}
'

{
  "id": "wep_01JXX7YQGPRPV1BZXA35QE7WDP",
  "description": "生产环境会话事件",
  "url": "https://example.com/managedagent/webhooks",
  "events": [
    "session.updated",
    "session.status_idled",
    "session.thread_terminated"
  ],
  "status": "ACTIVE",
  "disabled_reason": null,
  "consecutive_fail": 0,
  "last_success_at": null,
  "last_failure_at": null,
  "signing_secret": "whsec_xxx",
  "created_at": "2026-08-06T10:00:00Z",
  "updated_at": "2026-08-06T10:00:00Z",
  "request_id": "8e1d16e4"
}

Authorizations

string

header

required

DashScope API Key

Body

application/json

string

required

回调地址；允许 HTTP 或 HTTPS，端口不限，可用域名或公网 IP；私网、回环、链路本地和保留地址会被拒绝

string[]

required

可订阅的具名事件类型数组，不支持通配订阅

string

描述，最长 256 个字符

Response

201-application/json

string

Webhook ID，格式 wep_<ULID>

string | null

描述

string

回调地址

string[]

订阅的具名事件类型

enum<string>

Webhook 状态

Available options:ACTIVE,DISABLED

string | null

禁用原因，未禁用时为 null

integer

当前连续失败数，新建时为 0

string | null

最近成功投递时间，新建时为 null

string | null

最近失败投递时间，新建时为 null

string

验签密钥，格式 whsec_ 加标准 Base64 文本。仅在创建和重置成功响应返回

string

创建时间，ISO 8601

string

最近更新时间，ISO 8601

string

本次请求的唯一标识

cURL

curl --request POST \
  --url 'https://{workspace_id}.{region}.maas.aliyuncs.com/api/v1/agentstudio/webhook_endpoints' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "description": "生产环境会话事件",
  "url": "https://example.com/managedagent/webhooks",
  "events": [
    "session.updated",
    "session.status_idled",
    "session.thread_terminated"
  ]
}
'

{
  "id": "wep_01JXX7YQGPRPV1BZXA35QE7WDP",
  "description": "生产环境会话事件",
  "url": "https://example.com/managedagent/webhooks",
  "events": [
    "session.updated",
    "session.status_idled",
    "session.thread_terminated"
  ],
  "status": "ACTIVE",
  "disabled_reason": null,
  "consecutive_fail": 0,
  "last_success_at": null,
  "last_failure_at": null,
  "signing_secret": "whsec_xxx",
  "created_at": "2026-08-06T10:00:00Z",
  "updated_at": "2026-08-06T10:00:00Z",
  "request_id": "8e1d16e4"
}