# Webhook 事件结构参考

> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。

当 Agent 运行状态、资源变更或凭证刷新等订阅事件发生时，Managed Agents Webhook 会向接入点推送统一事件信封。本文列出当前可订阅的业务事件，并说明用于验证接收链路的 `webhook.test` 测试事件。Webhook 事件是独立通知，不等同于 Session Events 查询或 SSE 返回的原始事件。

每个事件使用以下统一信封。外层 `type` 固定为 `event`，`id` 是以 `whe-` 开头的 Webhook 事件 ID；`data.type` 是业务事件类型，`data.id` 是触发事件的资源 ID。

```json
{
  "type": "event",
  "id": "whe-20261012080500-f6g7h",
  "created_at": "2026-10-12T08:05:00Z",
  "data": {
    "type": "session.status_idled",
    "id": "sesn-20261012080000-k1l2m"
  }
}
```

事件正文生成后保持不变；同一事件向多个接入点投递或重试时，外层 `id`、`created_at` 和正文均不变。

> **说明**
>
> * Webhook 不保证严格顺序或恰好一次投递。接收端应按外层 `id` 去重，并通过资源查询接口读取当前状态。
> * `session.status_running` 映射为 `session.status_run_started`；`session.status_idle` 映射为 `session.status_idled`。原 Session 事件名称不变。
> * `session.status_idled` 只表示 Session 已进入空闲状态，不表示当前轮次正常结束。使用 `data.id` 查询该 Session 的历史事件，并根据业务侧记录的本轮边界定位对应的 `session.status_idle`；无法确认对应关系时，不要仅凭最近一条 `end_turn` 自动推进业务。Webhook 外层 `whe-` ID 不能作为 Session Event ID 使用。
> * 线程事件的 `data.id` 是所属 Session ID，`data.session_thread_id` 是发生状态变化的线程 ID。
> * 凭证事件的 `data.id` 是凭证 ID，`data.vault_id` 是所属 Vault ID；删除事件保留删除前的所属关系。
> * 使用 [查询 Webhook 事件列表](/docs/list-webhook-events-api) 或 [查询 Webhook 事件详情](/docs/get-webhook-event-api) 读取最近 7 天内与接入点关联的冻结事件信封。
> * 回调验签、重试和停用规则请参见 [使用 Webhook 接收事件通知](/docs/receive-webhook-events)。

## 服务端推送事件（响应）

### session.status_run_started

> Session 状态转换为运行中时触发。每次进入运行状态都会生成事件。

**type** `string` | 对象类型

`session.status_run_started.type`

对象类型，固定为 `event`。

**id** `string` | 事件 ID

`session.status_run_started.id`

Webhook 事件 ID，以 `whe-` 开头。该值与 `webhook-id` 请求头一致，用于幂等去重。

**created_at** `string` | 发生时间

`session.status_run_started.created_at`

事件发生时间，采用 RFC 3339 格式。测试事件返回生成时间。

**data** `object` | 事件数据

`session.status_run_started.data`

事件类型、资源 ID 和该事件需要的关联上下文。

**type** `string` | 事件类型

`session.status_run_started.data.type`

事件类型，固定为 `session.status_run_started`。

**id** `string` | 资源 ID

`session.status_run_started.data.id`

触发事件的 Session ID。

---

### session.status_idled

> Session 状态转换为空闲时触发。该事件不携带 `stop_reason`，也不表示当前轮次正常结束；需要按业务侧记录的本轮边界查询 Session 历史中的 `session.status_idle` 事件判断停止原因。

**type** `string` | 对象类型

`session.status_idled.type`

对象类型，固定为 `event`。

**id** `string` | 事件 ID

`session.status_idled.id`

Webhook 事件 ID，以 `whe-` 开头。该值与 `webhook-id` 请求头一致，用于幂等去重。

**created_at** `string` | 发生时间

`session.status_idled.created_at`

事件发生时间，采用 RFC 3339 格式。测试事件返回生成时间。

**data** `object` | 事件数据

`session.status_idled.data`

事件类型、资源 ID 和该事件需要的关联上下文。

**type** `string` | 事件类型

`session.status_idled.data.type`

事件类型，固定为 `session.status_idled`。

**id** `string` | 资源 ID

`session.status_idled.data.id`

触发事件的 Session ID。

---

### session.status_terminated

> Session 进入终止状态时触发。

**type** `string` | 对象类型

`session.status_terminated.type`

对象类型，固定为 `event`。

**id** `string` | 事件 ID

`session.status_terminated.id`

Webhook 事件 ID，以 `whe-` 开头。该值与 `webhook-id` 请求头一致，用于幂等去重。

**created_at** `string` | 发生时间

`session.status_terminated.created_at`

事件发生时间，采用 RFC 3339 格式。测试事件返回生成时间。

**data** `object` | 事件数据

`session.status_terminated.data`

事件类型、资源 ID 和该事件需要的关联上下文。

**type** `string` | 事件类型

`session.status_terminated.data.type`

事件类型，固定为 `session.status_terminated`。

**id** `string` | 资源 ID

`session.status_terminated.data.id`

触发事件的 Session ID。

---

### span.outcome_evaluation_end

> 单次迭代的结果评估结束时触发，不表示整个 Session 已完成。

**type** `string` | 对象类型

`span.outcome_evaluation_end.type`

对象类型，固定为 `event`。

**id** `string` | 事件 ID

`span.outcome_evaluation_end.id`

Webhook 事件 ID，以 `whe-` 开头。该值与 `webhook-id` 请求头一致，用于幂等去重。

**created_at** `string` | 发生时间

`span.outcome_evaluation_end.created_at`

事件发生时间，采用 RFC 3339 格式。测试事件返回生成时间。

**data** `object` | 事件数据

`span.outcome_evaluation_end.data`

事件类型、资源 ID 和该事件需要的关联上下文。

**type** `string` | 事件类型

`span.outcome_evaluation_end.data.type`

事件类型，固定为 `span.outcome_evaluation_end`。

**id** `string` | 资源 ID

`span.outcome_evaluation_end.data.id`

触发事件的 Session ID。

---

### session.error

> Session 执行过程中发生业务错误时触发，不表示投递失败或 Session 已终止。

**type** `string` | 对象类型

`session.error.type`

对象类型，固定为 `event`。

**id** `string` | 事件 ID

`session.error.id`

Webhook 事件 ID，以 `whe-` 开头。该值与 `webhook-id` 请求头一致，用于幂等去重。

**created_at** `string` | 发生时间

`session.error.created_at`

事件发生时间，采用 RFC 3339 格式。测试事件返回生成时间。

**data** `object` | 事件数据

`session.error.data`

事件类型、资源 ID 和该事件需要的关联上下文。

**type** `string` | 事件类型

`session.error.data.type`

事件类型，固定为 `session.error`。

**id** `string` | 资源 ID

`session.error.data.id`

触发事件的 Session ID。

---

### session.thread_status_running

> Session 线程开始处理任务并进入运行状态时触发。

**type** `string` | 对象类型

`session.thread_status_running.type`

对象类型，固定为 `event`。

**id** `string` | 事件 ID

`session.thread_status_running.id`

Webhook 事件 ID，以 `whe-` 开头。该值与 `webhook-id` 请求头一致，用于幂等去重。

**created_at** `string` | 发生时间

`session.thread_status_running.created_at`

事件发生时间，采用 RFC 3339 格式。测试事件返回生成时间。

**data** `object` | 事件数据

`session.thread_status_running.data`

事件类型、资源 ID 和该事件需要的关联上下文。

**type** `string` | 事件类型

`session.thread_status_running.data.type`

事件类型，固定为 `session.thread_status_running`。

**id** `string` | 资源 ID

`session.thread_status_running.data.id`

触发事件的 Session ID。

**session_thread_id** `string` | 线程 ID

`session.thread_status_running.data.session_thread_id`

状态发生变化的 Session 线程 ID。

---

### session.thread_status_idle

> Session 线程处理完当前任务并进入空闲状态时触发。

**type** `string` | 对象类型

`session.thread_status_idle.type`

对象类型，固定为 `event`。

**id** `string` | 事件 ID

`session.thread_status_idle.id`

Webhook 事件 ID，以 `whe-` 开头。该值与 `webhook-id` 请求头一致，用于幂等去重。

**created_at** `string` | 发生时间

`session.thread_status_idle.created_at`

事件发生时间，采用 RFC 3339 格式。测试事件返回生成时间。

**data** `object` | 事件数据

`session.thread_status_idle.data`

事件类型、资源 ID 和该事件需要的关联上下文。

**type** `string` | 事件类型

`session.thread_status_idle.data.type`

事件类型，固定为 `session.thread_status_idle`。

**id** `string` | 资源 ID

`session.thread_status_idle.data.id`

触发事件的 Session ID。

**session_thread_id** `string` | 线程 ID

`session.thread_status_idle.data.session_thread_id`

状态发生变化的 Session 线程 ID。

---

### session.thread_status_terminated

> Session 线程进入终止状态时触发。

**type** `string` | 对象类型

`session.thread_status_terminated.type`

对象类型，固定为 `event`。

**id** `string` | 事件 ID

`session.thread_status_terminated.id`

Webhook 事件 ID，以 `whe-` 开头。该值与 `webhook-id` 请求头一致，用于幂等去重。

**created_at** `string` | 发生时间

`session.thread_status_terminated.created_at`

事件发生时间，采用 RFC 3339 格式。测试事件返回生成时间。

**data** `object` | 事件数据

`session.thread_status_terminated.data`

事件类型、资源 ID 和该事件需要的关联上下文。

**type** `string` | 事件类型

`session.thread_status_terminated.data.type`

事件类型，固定为 `session.thread_status_terminated`。

**id** `string` | 资源 ID

`session.thread_status_terminated.data.id`

触发事件的 Session ID。

**session_thread_id** `string` | 线程 ID

`session.thread_status_terminated.data.session_thread_id`

状态发生变化的 Session 线程 ID。

---

### session.updated

> 通过 Session 更新接口成功修改 Session 时触发。

**type** `string` | 对象类型

`session.updated.type`

对象类型，固定为 `event`。

**id** `string` | 事件 ID

`session.updated.id`

Webhook 事件 ID，以 `whe-` 开头。该值与 `webhook-id` 请求头一致，用于幂等去重。

**created_at** `string` | 发生时间

`session.updated.created_at`

事件发生时间，采用 RFC 3339 格式。测试事件返回生成时间。

**data** `object` | 事件数据

`session.updated.data`

事件类型、资源 ID 和该事件需要的关联上下文。

**type** `string` | 事件类型

`session.updated.data.type`

事件类型，固定为 `session.updated`。

**id** `string` | 资源 ID

`session.updated.data.id`

触发事件的 Session ID。

---

### session.deleted

> 通过 Session 删除接口成功删除 Session 时触发。

**type** `string` | 对象类型

`session.deleted.type`

对象类型，固定为 `event`。

**id** `string` | 事件 ID

`session.deleted.id`

Webhook 事件 ID，以 `whe-` 开头。该值与 `webhook-id` 请求头一致，用于幂等去重。

**created_at** `string` | 发生时间

`session.deleted.created_at`

事件发生时间，采用 RFC 3339 格式。测试事件返回生成时间。

**data** `object` | 事件数据

`session.deleted.data`

事件类型、资源 ID 和该事件需要的关联上下文。

**type** `string` | 事件类型

`session.deleted.data.type`

事件类型，固定为 `session.deleted`。

**id** `string` | 资源 ID

`session.deleted.data.id`

触发事件的 Session ID。

---

### agent.created

> Agent 创建成功时触发。

**type** `string` | 对象类型

`agent.created.type`

对象类型，固定为 `event`。

**id** `string` | 事件 ID

`agent.created.id`

Webhook 事件 ID，以 `whe-` 开头。该值与 `webhook-id` 请求头一致，用于幂等去重。

**created_at** `string` | 发生时间

`agent.created.created_at`

事件发生时间，采用 RFC 3339 格式。测试事件返回生成时间。

**data** `object` | 事件数据

`agent.created.data`

事件类型、资源 ID 和该事件需要的关联上下文。

**type** `string` | 事件类型

`agent.created.data.type`

事件类型，固定为 `agent.created`。

**id** `string` | 资源 ID

`agent.created.data.id`

触发事件的 Agent ID。

---

### agent.updated

> Agent 更新成功时触发。

**type** `string` | 对象类型

`agent.updated.type`

对象类型，固定为 `event`。

**id** `string` | 事件 ID

`agent.updated.id`

Webhook 事件 ID，以 `whe-` 开头。该值与 `webhook-id` 请求头一致，用于幂等去重。

**created_at** `string` | 发生时间

`agent.updated.created_at`

事件发生时间，采用 RFC 3339 格式。测试事件返回生成时间。

**data** `object` | 事件数据

`agent.updated.data`

事件类型、资源 ID 和该事件需要的关联上下文。

**type** `string` | 事件类型

`agent.updated.data.type`

事件类型，固定为 `agent.updated`。

**id** `string` | 资源 ID

`agent.updated.data.id`

触发事件的 Agent ID。

---

### agent.deleted

> Agent 删除成功时触发。

**type** `string` | 对象类型

`agent.deleted.type`

对象类型，固定为 `event`。

**id** `string` | 事件 ID

`agent.deleted.id`

Webhook 事件 ID，以 `whe-` 开头。该值与 `webhook-id` 请求头一致，用于幂等去重。

**created_at** `string` | 发生时间

`agent.deleted.created_at`

事件发生时间，采用 RFC 3339 格式。测试事件返回生成时间。

**data** `object` | 事件数据

`agent.deleted.data`

事件类型、资源 ID 和该事件需要的关联上下文。

**type** `string` | 事件类型

`agent.deleted.data.type`

事件类型，固定为 `agent.deleted`。

**id** `string` | 资源 ID

`agent.deleted.data.id`

触发事件的 Agent ID。

---

### environment.created

> Environment 创建成功时触发。

**type** `string` | 对象类型

`environment.created.type`

对象类型，固定为 `event`。

**id** `string` | 事件 ID

`environment.created.id`

Webhook 事件 ID，以 `whe-` 开头。该值与 `webhook-id` 请求头一致，用于幂等去重。

**created_at** `string` | 发生时间

`environment.created.created_at`

事件发生时间，采用 RFC 3339 格式。测试事件返回生成时间。

**data** `object` | 事件数据

`environment.created.data`

事件类型、资源 ID 和该事件需要的关联上下文。

**type** `string` | 事件类型

`environment.created.data.type`

事件类型，固定为 `environment.created`。

**id** `string` | 资源 ID

`environment.created.data.id`

触发事件的 Environment ID。

---

### environment.updated

> Environment 更新成功时触发。

**type** `string` | 对象类型

`environment.updated.type`

对象类型，固定为 `event`。

**id** `string` | 事件 ID

`environment.updated.id`

Webhook 事件 ID，以 `whe-` 开头。该值与 `webhook-id` 请求头一致，用于幂等去重。

**created_at** `string` | 发生时间

`environment.updated.created_at`

事件发生时间，采用 RFC 3339 格式。测试事件返回生成时间。

**data** `object` | 事件数据

`environment.updated.data`

事件类型、资源 ID 和该事件需要的关联上下文。

**type** `string` | 事件类型

`environment.updated.data.type`

事件类型，固定为 `environment.updated`。

**id** `string` | 资源 ID

`environment.updated.data.id`

触发事件的 Environment ID。

---

### environment.deleted

> Environment 删除成功时触发。

**type** `string` | 对象类型

`environment.deleted.type`

对象类型，固定为 `event`。

**id** `string` | 事件 ID

`environment.deleted.id`

Webhook 事件 ID，以 `whe-` 开头。该值与 `webhook-id` 请求头一致，用于幂等去重。

**created_at** `string` | 发生时间

`environment.deleted.created_at`

事件发生时间，采用 RFC 3339 格式。测试事件返回生成时间。

**data** `object` | 事件数据

`environment.deleted.data`

事件类型、资源 ID 和该事件需要的关联上下文。

**type** `string` | 事件类型

`environment.deleted.data.type`

事件类型，固定为 `environment.deleted`。

**id** `string` | 资源 ID

`environment.deleted.data.id`

触发事件的 Environment ID。

---

### memory_store.created

> Memory Store 创建成功时触发。

**type** `string` | 对象类型

`memory_store.created.type`

对象类型，固定为 `event`。

**id** `string` | 事件 ID

`memory_store.created.id`

Webhook 事件 ID，以 `whe-` 开头。该值与 `webhook-id` 请求头一致，用于幂等去重。

**created_at** `string` | 发生时间

`memory_store.created.created_at`

事件发生时间，采用 RFC 3339 格式。测试事件返回生成时间。

**data** `object` | 事件数据

`memory_store.created.data`

事件类型、资源 ID 和该事件需要的关联上下文。

**type** `string` | 事件类型

`memory_store.created.data.type`

事件类型，固定为 `memory_store.created`。

**id** `string` | 资源 ID

`memory_store.created.data.id`

触发事件的 Memory Store ID。

---

### memory_store.deleted

> Memory Store 删除成功时触发。

**type** `string` | 对象类型

`memory_store.deleted.type`

对象类型，固定为 `event`。

**id** `string` | 事件 ID

`memory_store.deleted.id`

Webhook 事件 ID，以 `whe-` 开头。该值与 `webhook-id` 请求头一致，用于幂等去重。

**created_at** `string` | 发生时间

`memory_store.deleted.created_at`

事件发生时间，采用 RFC 3339 格式。测试事件返回生成时间。

**data** `object` | 事件数据

`memory_store.deleted.data`

事件类型、资源 ID 和该事件需要的关联上下文。

**type** `string` | 事件类型

`memory_store.deleted.data.type`

事件类型，固定为 `memory_store.deleted`。

**id** `string` | 资源 ID

`memory_store.deleted.data.id`

触发事件的 Memory Store ID。

---

### vault.created

> Vault 创建成功时触发。

**type** `string` | 对象类型

`vault.created.type`

对象类型，固定为 `event`。

**id** `string` | 事件 ID

`vault.created.id`

Webhook 事件 ID，以 `whe-` 开头。该值与 `webhook-id` 请求头一致，用于幂等去重。

**created_at** `string` | 发生时间

`vault.created.created_at`

事件发生时间，采用 RFC 3339 格式。测试事件返回生成时间。

**data** `object` | 事件数据

`vault.created.data`

事件类型、资源 ID 和该事件需要的关联上下文。

**type** `string` | 事件类型

`vault.created.data.type`

事件类型，固定为 `vault.created`。

**id** `string` | 资源 ID

`vault.created.data.id`

触发事件的 Vault ID。

---

### vault.deleted

> Vault 删除成功时触发。

**type** `string` | 对象类型

`vault.deleted.type`

对象类型，固定为 `event`。

**id** `string` | 事件 ID

`vault.deleted.id`

Webhook 事件 ID，以 `whe-` 开头。该值与 `webhook-id` 请求头一致，用于幂等去重。

**created_at** `string` | 发生时间

`vault.deleted.created_at`

事件发生时间，采用 RFC 3339 格式。测试事件返回生成时间。

**data** `object` | 事件数据

`vault.deleted.data`

事件类型、资源 ID 和该事件需要的关联上下文。

**type** `string` | 事件类型

`vault.deleted.data.type`

事件类型，固定为 `vault.deleted`。

**id** `string` | 资源 ID

`vault.deleted.data.id`

触发事件的 Vault ID。

---

### vault_credential.created

> Vault 凭证创建成功时触发。

**type** `string` | 对象类型

`vault_credential.created.type`

对象类型，固定为 `event`。

**id** `string` | 事件 ID

`vault_credential.created.id`

Webhook 事件 ID，以 `whe-` 开头。该值与 `webhook-id` 请求头一致，用于幂等去重。

**created_at** `string` | 发生时间

`vault_credential.created.created_at`

事件发生时间，采用 RFC 3339 格式。测试事件返回生成时间。

**data** `object` | 事件数据

`vault_credential.created.data`

事件类型、资源 ID 和该事件需要的关联上下文。

**type** `string` | 事件类型

`vault_credential.created.data.type`

事件类型，固定为 `vault_credential.created`。

**id** `string` | 资源 ID

`vault_credential.created.data.id`

触发事件的凭证 ID。

**vault_id** `string` | Vault ID

`vault_credential.created.data.vault_id`

凭证所属的 Vault ID。删除事件保留删除前的所属关系。

---

### vault_credential.deleted

> Vault 凭证被直接删除，或随所属 Vault 删除时触发。

**type** `string` | 对象类型

`vault_credential.deleted.type`

对象类型，固定为 `event`。

**id** `string` | 事件 ID

`vault_credential.deleted.id`

Webhook 事件 ID，以 `whe-` 开头。该值与 `webhook-id` 请求头一致，用于幂等去重。

**created_at** `string` | 发生时间

`vault_credential.deleted.created_at`

事件发生时间，采用 RFC 3339 格式。测试事件返回生成时间。

**data** `object` | 事件数据

`vault_credential.deleted.data`

事件类型、资源 ID 和该事件需要的关联上下文。

**type** `string` | 事件类型

`vault_credential.deleted.data.type`

事件类型，固定为 `vault_credential.deleted`。

**id** `string` | 资源 ID

`vault_credential.deleted.data.id`

触发事件的凭证 ID。

**vault_id** `string` | Vault ID

`vault_credential.deleted.data.vault_id`

凭证所属的 Vault ID。删除事件保留删除前的所属关系。

---

### vault_credential.refresh_failed

> 平台刷新 OAuth 凭证失败时触发；未执行刷新时不产生该事件。

**type** `string` | 对象类型

`vault_credential.refresh_failed.type`

对象类型，固定为 `event`。

**id** `string` | 事件 ID

`vault_credential.refresh_failed.id`

Webhook 事件 ID，以 `whe-` 开头。该值与 `webhook-id` 请求头一致，用于幂等去重。

**created_at** `string` | 发生时间

`vault_credential.refresh_failed.created_at`

事件发生时间，采用 RFC 3339 格式。测试事件返回生成时间。

**data** `object` | 事件数据

`vault_credential.refresh_failed.data`

事件类型、资源 ID 和该事件需要的关联上下文。

**type** `string` | 事件类型

`vault_credential.refresh_failed.data.type`

事件类型，固定为 `vault_credential.refresh_failed`。

**id** `string` | 资源 ID

`vault_credential.refresh_failed.data.id`

触发事件的凭证 ID。

**vault_id** `string` | Vault ID

`vault_credential.refresh_failed.data.vault_id`

凭证所属的 Vault ID。删除事件保留删除前的所属关系。

---

### webhook.test

> 调用发送 Webhook 测试事件接口时生成。该事件不可订阅，只向目标接入点投递一次。

**type** `string` | 对象类型

`webhook.test.type`

对象类型，固定为 `event`。

**id** `string` | 事件 ID

`webhook.test.id`

Webhook 事件 ID，以 `whe-` 开头。该值与 `webhook-id` 请求头一致，用于幂等去重。

**created_at** `string` | 发生时间

`webhook.test.created_at`

事件发生时间，采用 RFC 3339 格式。测试事件返回生成时间。

**data** `object` | 事件数据

`webhook.test.data`

事件类型、资源 ID 和该事件需要的关联上下文。

**type** `string` | 事件类型

`webhook.test.data.type`

事件类型，固定为 `webhook.test`。

**id** `string` | 资源 ID

`webhook.test.data.id`

被测试的 Webhook 接入点 ID。

---