Copy

Webhook 当前为 Beta 功能，接口、字段和行为可能在后续版本中调整。

Webhook Endpoint 保存接收地址和订阅事件。事件发生后，Qoder Cloud Agents 会向 Endpoint 发送 POST 请求。Webhook 适合接收 Schedule Run 等无法依赖长连接等待的异步结果。本组接口只管理当前个人空间或当前企业 Workspace 下、通过 Forward Mode 创建的 Endpoint。其他空间或其他模式创建的 Endpoint 不会出现在列表中，也不能通过本组接口操作。

接口

方法	路径	说明
`POST`	`/api/v1/forward/webhook/endpoints`	创建 Endpoint
`GET`	`/api/v1/forward/webhook/endpoints`	列出 Endpoints
`GET`	`/api/v1/forward/webhook/endpoints/{endpoint_id}`	获取 Endpoint
`PUT`	`/api/v1/forward/webhook/endpoints/{endpoint_id}`	更新 Endpoint
`DELETE`	`/api/v1/forward/webhook/endpoints/{endpoint_id}`	删除 Endpoint
`POST`	`/api/v1/forward/webhook/endpoints/{endpoint_id}/enable`	启用 Endpoint
`POST`	`/api/v1/forward/webhook/endpoints/{endpoint_id}/disable`	停用 Endpoint
`POST`	`/api/v1/forward/webhook/endpoints/{endpoint_id}/test`	发送测试事件

认证

Webhook Endpoint 是管理类资源。以上接口接受 Qoder PAT 或管理员 Service Account Token：

Authorization: Bearer <PAT 或管理员 SAT>

Identity 级 Service Account Token 不能管理 Webhook Endpoint。

公开事件

Forward 当前支持以下 29 种公开事件，与 Forward 控制台的订阅目录一致。同一 Endpoint 可以同时订阅 Schedule 业务事件和 Managed Agents 资源事件；创建或更新时，将表中的完整事件名填入 events 数组。

Schedule 与 Schedule Run

事件类型	触发时机
`forward.schedule.created`	Schedule 创建成功。
`forward.schedule_run.succeeded`	Schedule Run 成功完成，`data.status` 为 `completed`。
`forward.schedule_run.failed`	Schedule Run 执行失败，`data.status` 为 `failed`。

Schedule Run 的执行结果与渠道推送结果不同，渠道推送状态由 data.push_status 表示。

Session

事件类型	触发时机
`session.status_run_started`	Session 开始一轮运行。
`session.status_idled`	Session 本轮运行结束或取消后进入空闲状态。
`session.status_terminated`	Session 被终止。
`session.updated`	Session 的标题、元数据等属性更新。
`session.deleted`	Session 被删除。

session.status_idled 表示会话进入空闲状态，不等同于业务执行成功；应查询 Session 的输出和状态确认结果。

Session Thread

事件类型	触发时机
`session.thread_created`	Session 中创建新的子线程。
`session.thread_idled`	线程本轮运行结束、被中断，或暂停等待外部动作（如工具结果）。
`session.thread_terminated`	线程被终止。

线程事件的 data.id 是所属 Session ID，data.session_thread_id 标识具体线程。session.thread_idled 不一定表示线程任务完成；等待外部动作时，线程状态为 blocked。

Agent

事件类型	触发时机
`agent.created`	Managed Agent 创建成功。
`agent.updated`	Managed Agent 配置更新。
`agent.archived`	Managed Agent 被归档。
`agent.deleted`	Managed Agent 被删除。

这里的 Agent 指 Managed Agents 资源，不是 Forward Template；这些事件不表示 Template 的生命周期变化。

Environment

事件类型	触发时机
`environment.created`	Environment 创建成功。
`environment.updated`	Environment 配置更新。
`environment.archived`	Environment 被归档。
`environment.deleted`	Environment 被删除。

Memory Store

事件类型	触发时机
`memory_store.created`	Memory Store 创建成功。
`memory_store.archived`	Memory Store 被归档。
`memory_store.deleted`	Memory Store 被删除。

Vault 与 Vault Credential

事件类型	触发时机
`vault.created`	Vault 创建成功。
`vault.archived`	Vault 被归档。
`vault.deleted`	Vault 被删除。
`vault_credential.created`	Vault Credential 创建成功。
`vault_credential.archived`	凭据被归档，包括所属 Vault 归档时的级联归档。
`vault_credential.deleted`	凭据被删除，包括所属 Vault 删除时的级联删除。
`vault_credential.refresh_failed`	OAuth 凭据刷新失败。

凭据事件的 data.id 是凭据 ID，data.vault_id 是所属 Vault ID；事件不包含凭据秘密内容。

订阅规则与测试事件

events 至少包含一项，支持完整事件名或全局通配符 *；不支持 forward.*、session.* 等前缀通配符。
订阅 * 可以接收当前及未来可投递的全部事件。生产环境建议显式订阅所需的公开事件，并兼容暂不识别的事件类型。
接口接受符合 namespace.name 形式的事件名，不代表该事件一定会产生；只有上述公开目录中的事件具有 Forward 投递契约。
Forward 不公开 Deployment 和 Deployment Run 事件，不应将 Managed Agents 的全部事件直接视为 Forward 支持的事件。
webhook.test 是发送测试事件接口生成的定向测试事件，无需加入订阅列表，也不计入上述 29 种业务和资源事件。

例如，同时接收会话空闲通知和 Schedule Run 的最终结果：

{
  "events": [
    "session.status_idled",
    "forward.schedule_run.succeeded",
    "forward.schedule_run.failed"
  ]
}

事件载荷、签名校验和幂等处理见接收 Webhook 事件。

使用流程

准备一个可接收公网 HTTPS POST 请求的地址。
创建 Endpoint，并安全保存创建响应中的 signing_secret。
调用测试接口验证网络连通性和签名处理。
订阅所需事件，并使用 Webhook-ID 对重复投递去重。

Webhook 使用至少一次投递语义，同一事件可能被投递多次。接收端应尽快返回 2xx，再异步处理耗时业务。

​接口

​认证

​公开事件

​Schedule 与 Schedule Run

​Session

​Session Thread

​Agent

​Environment

​Memory Store

​Vault 与 Vault Credential

​订阅规则与测试事件

​使用流程

接口

认证

公开事件

Schedule 与 Schedule Run

Session

Session Thread

Agent

Environment

Memory Store

Vault 与 Vault Credential

订阅规则与测试事件

使用流程