Skip to main content
集成 Agent

Webhooks

通过 HTTP Webhook 订阅 Cloud Agents 生命周期事件，包括端点管理、投递行为与支持的事件目录。

一、概述

Webhook 是 Qoder Cloud Agents 提供的事件驱动推送机制。当 Agent、Session 等资源发生生命周期变化时，系统以 HTTP POST 方式将结构化事件推送到开发者注册的 URL，无需轮询即可实时获取状态变更。 核心特性：
  • 事件驱动推送 — 资源状态变更时主动通知，无需客户端轮询
  • 信封结构 — 统一的 BetaWebhookEvent { id, created_at, data, type:"event" } 格式
  • 投递语义 — at-least-once 保证；指数退避重试
适用场景：
场景说明
异步任务完成通知Session 执行完毕后触发下游流程
Agent 配置变更审计记录 Agent 创建/更新/删除操作
多 Agent 协作编排Thread 状态变更驱动子任务调度
运维监控告警连续失败计数超阈值时告警

二、Domain Types

本节定义 Webhook 事件的数据结构。每种事件类型的 data 字段遵循统一的 object 格式，包含资源 ID、事件类型及事件特定的额外字段。

Session 生命周期事件

Webhook Session Updated Event Data

  • WebhookSessionUpdatedEventData object { id, type }
    • id: string 触发事件的 Session ID。
    • type: "session.updated"
      • "session.updated"
      Session 元数据（如 title、metadata 等）被修改时触发。

Webhook Session Deleted Event Data

  • WebhookSessionDeletedEventData object { id, type }
    • id: string 触发事件的 Session ID。
    • type: "session.deleted"
      • "session.deleted"
      Session 被永久删除时触发。删除后该 Session 的所有数据将不可恢复。

Session 状态事件

Webhook Session Status Run Started Event Data

  • WebhookSessionStatusRunStartedEventData object { id, type }
    • id: string 触发事件的 Session ID。
    • type: "session.status_run_started"
      • "session.status_run_started"
      Agent 开始一轮运行时触发。标志着 Session 进入 running 状态，正在执行用户指令。

Webhook Session Status Idled Event Data

  • WebhookSessionStatusIdledEventData object { id, type }
    • id: string 触发事件的 Session ID。
    • type: "session.status_idled"
      • "session.status_idled"
      一轮 turn 执行完成，Session 回到 idle 状态时触发。此时可安全地读取 Session 的最新输出。

Session Thread 事件

适用于多 Agent 协作场景。Thread 事件在 Session 事件基础上额外携带 session_thread_id 字段，标识具体的执行线程。

Webhook Session Thread Created Event Data

  • WebhookSessionThreadCreatedEventData object { id, type, session_thread_id }
    • id: string 触发事件的 Session ID。
    • type: "session.thread_created"
      • "session.thread_created"
      新的 Session Thread 被创建时触发。常见于子 Agent 协作场景中，主 Agent 派生子线程执行任务。
    • session_thread_id: string 所属的 Session Thread ID。

Webhook Session Thread Idled Event Data

  • WebhookSessionThreadIdledEventData object { id, type, session_thread_id }
    • id: string 触发事件的 Session ID。
    • type: "session.thread_idled"
      • "session.thread_idled"
      Session Thread 一轮执行结束进入 idle 状态时触发。表示该线程已完成当前任务，可读取结果。
    • session_thread_id: string 所属的 Session Thread ID。

Webhook Session Thread Terminated Event Data

  • WebhookSessionThreadTerminatedEventData object { id, type, session_thread_id }
    • id: string 触发事件的 Session ID。
    • type: "session.thread_terminated"
      • "session.thread_terminated"
      Session Thread 被终止时触发。Thread 终止后不可恢复，需创建新 Thread 继续工作。
    • session_thread_id: string 所属的 Session Thread ID。

Agent 生命周期事件

Webhook Agent Created Event Data

  • WebhookAgentCreatedEventData object { id, type }
    • id: string 触发事件的 Agent ID。
    • type: "agent.created"
      • "agent.created"
      Agent 被成功创建时触发。通过 POST /agents 接口创建 Agent 后，系统发送此事件。

Webhook Agent Updated Event Data

  • WebhookAgentUpdatedEventData object { id, type }
    • id: string 触发事件的 Agent ID。
    • type: "agent.updated"
      • "agent.updated"
      Agent 配置被更新时触发。

Webhook Agent Archived Event Data

  • WebhookAgentArchivedEventData object { id, type }
    • id: string 触发事件的 Agent ID。
    • type: "agent.archived"
      • "agent.archived"
      Agent 被归档时触发。归档后 Agent 不再接受新的 Session 创建请求。

Webhook Agent Deleted Event Data

  • WebhookAgentDeletedEventData object { id, type }
    • id: string 触发事件的 Agent ID。
    • type: "agent.deleted"
      • "agent.deleted"
      Agent 被删除时触发。删除后该 Agent 的所有配置数据将不可恢复。

Deployment Run 事件

Deployment Run 事件的 id 为 Deployment Run ID。
  • WebhookDeploymentRunStartedEventData object { id, type: "deployment_run.started" }
  • WebhookDeploymentRunSucceededEventData object { id, type: "deployment_run.succeeded" }
  • WebhookDeploymentRunFailedEventData object { id, type: "deployment_run.failed" }

三、Webhook Endpoint API

管理 Webhook 端点的 CRUD 接口。通过这些接口可以创建、查询、更新、删除 Webhook 端点，以及发送测试事件和控制端点的启用/禁用状态。 Base URL：
区域地址
Globalhttps://api.qoder.com/api/v1/cloud
CNhttps://api.qoder.com.cn/api/v1/cloud
认证方式： 所有接口均需要在请求头中携带个人访问令牌（PAT）或服务账号令牌（SAT）： 
Authorization: Bearer $QODER_ACCESS_TOKEN

POST /webhook_endpoints

创建一个新的 Webhook 端点。 请求参数：
字段类型必填说明
urlstring是接收事件推送的公网 HTTPS URL，必须使用 443 端口
descriptionstring否端点描述，便于管理识别
eventsstring[]是订阅的具名事件类型列表，可选值见第五节
响应： 201 Created 
{
  "id": "5fc05310-4d9c-447e-a4b8-f124f17e1ff0",
  "url": "https://webhook.site/your-unique-path",
  "description": "quickstart demo",
  "events": ["session.status_idled", "session.thread_idled"],
  "active": true,
  "signing_secret": "whsec_BfJDodFEzmkdjAUf19-_XthSq6KbPKmRjfm9KFWMIuk",
  "created_at": "2026-07-02T18:17:30.069191+08:00"
}
注意： signing_secret 仅在创建时返回一次，请安全保存。
状态码：
状态码说明
201创建成功
400请求参数无效（如 URL 不是公网 HTTPS 443 地址、事件类型不合法）
401未授权，Token 无效或过期
422语义错误（如 URL 重复注册）
示例： 
curl -X POST https://api.qoder.com/api/v1/cloud/webhook_endpoints \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://webhook.site/your-unique-path",
    "description": "quickstart demo",
    "events": ["session.status_idled", "session.thread_idled"]
  }'

GET /webhook_endpoints

获取当前账户下所有 Webhook 端点列表。 请求参数： 无 响应： 200 OK 
{
  "data": [
    {
      "id": "700e7789-edab-41cb-b60a-210d0df38ab6",
      "url": "https://myapp.example.com/hooks/qoder",
      "description": "prod app hook",
      "events": ["session.status_idled", "session.thread_idled"],
      "active": true,
      "consecutive_fail": 0,
      "last_success_at": "2026-07-02T18:08:12.666783+08:00",
      "created_at": "2026-07-02T17:47:16.073822+08:00",
      "updated_at": "2026-07-02T17:47:16.073822+08:00"
    }
  ]
}
响应字段说明：
字段类型说明
idstring端点唯一标识
urlstring接收事件的 URL
descriptionstring端点描述
eventsstring[]订阅的事件类型列表
activeboolean是否启用
consecutive_failinteger连续投递失败次数
last_success_atstring最近一次成功投递时间（RFC 3339）
last_failure_atstring最近一次投递失败时间（RFC 3339），无失败记录时为 null
created_atstring创建时间（RFC 3339）
updated_atstring最近更新时间（RFC 3339）
示例： 
curl https://api.qoder.com/api/v1/cloud/webhook_endpoints \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"

GET /webhook_endpoints/{id}

获取指定 Webhook 端点的详细信息。 路径参数：
参数类型说明
idstringWebhook 端点 ID
响应： 200 OK 返回单个端点对象，结构与列表接口中的元素一致。 状态码：
状态码说明
200成功
404端点不存在
示例： 
curl https://api.qoder.com/api/v1/cloud/webhook_endpoints/700e7789-edab-41cb-b60a-210d0df38ab6 \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"

PUT /webhook_endpoints/{id}

更新指定 Webhook 端点的配置。 路径参数：
参数类型说明
idstringWebhook 端点 ID
请求参数：
字段类型必填说明
urlstring否更新接收事件推送的公网 HTTPS 443 URL
descriptionstring否更新端点描述
eventsstring[]否更新订阅的具名事件类型列表
响应： 200 OK 返回更新后的完整端点对象。 状态码：
状态码说明
200更新成功
400请求参数无效
404端点不存在
示例： 
curl -X PUT https://api.qoder.com/api/v1/cloud/webhook_endpoints/700e7789-edab-41cb-b60a-210d0df38ab6 \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["session.status_idled", "session.thread_idled", "agent.updated"],
    "description": "updated prod hook"
  }'

DELETE /webhook_endpoints/{id}

永久删除指定的 Webhook 端点。删除后所有未投递的事件将被丢弃。 路径参数：
参数类型说明
idstringWebhook 端点 ID
响应： 204 No Content 状态码：
状态码说明
204删除成功
404端点不存在
示例： 
curl -X DELETE https://api.qoder.com/api/v1/cloud/webhook_endpoints/700e7789-edab-41cb-b60a-210d0df38ab6 \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"

POST /webhook_endpoints/{id}/test

向指定端点发送一个测试事件，用于验证端点连通性和 Payload 处理逻辑。 路径参数：
参数类型说明
idstringWebhook 端点 ID
请求参数： 无 响应： 202 Accepted 
{"event_id": 433, "delivery_rows": 2}
响应字段说明：
字段类型说明
event_idinteger测试事件的内部 ID
delivery_rowsinteger事件发布的消息分区数
状态码：
状态码说明
202测试事件已发送
404端点不存在
示例： 
curl -X POST https://api.qoder.com/api/v1/cloud/webhook_endpoints/700e7789-edab-41cb-b60a-210d0df38ab6/test \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"

POST /webhook_endpoints/{id}/enable

启用一个被禁用的 Webhook 端点。启用后端点将重新接收事件推送。 路径参数：
参数类型说明
idstringWebhook 端点 ID
请求参数： 无 响应： 200 OK 返回启用后的端点对象（active: true）。 状态码：
状态码说明
200启用成功
404端点不存在
示例： 
curl -X POST https://api.qoder.com/api/v1/cloud/webhook_endpoints/700e7789-edab-41cb-b60a-210d0df38ab6/enable \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"

POST /webhook_endpoints/{id}/disable

禁用一个 Webhook 端点。禁用后端点将停止接收事件推送，但不会被删除。 路径参数：
参数类型说明
idstringWebhook 端点 ID
请求参数： 无 响应： 200 OK 返回禁用后的端点对象（active: false）。 状态码：
状态码说明
200禁用成功
404端点不存在
示例： 
curl -X POST https://api.qoder.com/api/v1/cloud/webhook_endpoints/700e7789-edab-41cb-b60a-210d0df38ab6/disable \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"

GET /webhook_events

列出 Webhook 事件投递记录，用于审计和排查。 请求参数： 无 响应： 200 OK 返回事件列表，包含事件的投递状态、时间戳等信息。 示例： 
curl https://api.qoder.com/api/v1/cloud/webhook_events \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"

GET /webhook_events/{id}

获取单个 Webhook 事件的详细信息。 路径参数：
参数类型说明
idstringWebhook 事件 ID
响应： 200 OK 状态码：
状态码说明
200成功
404事件不存在
示例： 
curl https://api.qoder.com/api/v1/cloud/webhook_events/433 \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"

错误响应格式

所有接口在遇到错误时，返回统一的错误结构： 
{
  "error": {
    "message": "Unknown event type: agent.updated",
    "type": "invalid_request_error"
  },
  "request_id": "cc865161-b25d-4d68-bad5-bf0363f6e0f9",
  "type": "error"
}
错误字段说明：
字段类型说明
error.messagestring人类可读的错误描述
error.typestring错误分类（如 invalid_request_error、not_found_error）
request_idstring请求追踪 ID，用于排查问题时提供给支持团队
typestring固定值 "error"
注意： 鉴权层（如 Token 无效或缺失）返回的 401 响应可能不遵循上述业务错误结构，而是由网关直接返回。

四、Webhook Delivery（投递机制）

投递方式

系统通过 HTTP POST 将事件推送到注册的 URL，请求格式如下：
  • Method: POST
  • Content-Type: application/json
  • Body: JSON 格式的信封结构（详见第六节）

请求头

每次投递包含以下 HTTP 请求头：
Header说明
Content-Typeapplication/json
User-AgentQoderCloudAgents-Webhook/1.0

重试策略

当投递失败时，系统采用指数退避策略进行重试：
尝试次数延迟说明
第 1 次立即首次投递
第 2 次1 秒第一次重试
第 3 次5 秒第二次重试
第 4 次30 秒最终重试
共计 4 次尝试（1 次投递 + 3 次重试）。全部失败后事件进入死信队列。

响应码处理

响应码范围处理方式
2xx投递成功，事件标记为已送达
4xx不重试，事件标记为已丢弃（客户端错误应由开发者修复）
5xx触发重试（服务端临时故障）
超时触发重试（默认超时 30 秒）

自动降级

当某个端点的 consecutive_fail 计数超过 20 时，系统将触发降级警告。建议开发者监控此指标，并在持续失败时检查：
  • 端点 URL 是否可达
  • SSL 证书是否有效
  • 服务端是否正常响应

五、Supported Event Types

当前可订阅并拥有真实发送链路的事件如下。events 只能使用表中的具名事件。
事件类型data 额外字段触发条件
session.updated—Session 元数据被修改
session.deleted—Session 被永久删除
session.status_run_started—Agent 开始一轮运行
session.status_idled—Turn 执行完成，回到 idle 状态
session.thread_createdsession_thread_id新的 Session Thread 被创建
session.thread_idledsession_thread_idThread 执行结束进入 idle
session.thread_terminatedsession_thread_idThread 被终止
agent.created—Agent 被创建
agent.updated—Agent 配置被更新
agent.archived—Agent 被归档
agent.deleted—Agent 被删除
deployment_run.started—一次 Deployment Run 开始执行
deployment_run.succeeded—一次 Deployment Run 执行成功
deployment_run.failed—一次 Deployment Run 执行失败

六、信封结构详解

所有 Webhook 事件均使用统一的信封（envelope）结构进行封装投递。

基础信封结构

{
  "id": "whe_a1b2c3d4e5f67890",
  "created_at": "2026-07-02T10:02:16Z",
  "type": "event",
  "data": {
    "id": "sess_019f224773fe71d79c5869bd089d159c",
    "type": "session.status_idled"
  }
}

Thread 事件信封

Thread 事件的 data 中额外包含 session_thread_id 字段： 
{
  "id": "whe_a1b2c3d4e5f67890",
  "created_at": "2026-07-02T10:02:17Z",
  "type": "event",
  "data": {
    "id": "sess_019f224773fe71d79c5869bd089d159c",
    "type": "session.thread_idled",
    "session_thread_id": "sthread_019f224..."
  }
}

字段说明

字段类型说明
idstring事件唯一标识，以 whe_ 开头；同一事件重试时保持不变
created_atstring事件创建时间，RFC 3339 UTC 格式
typestring固定值 "event"，标识这是一个事件信封
dataobject事件负载，包含触发资源的信息
data.idstring触发事件的资源 ID（如 Session、Agent 或 Deployment Run ID）
data.typestring事件类型字符串，如 "session.status_idled"、"agent.updated"
data.session_thread_idstring（仅 Thread 事件）所属的 Session Thread ID

幂等性处理

信封中的 id 字段可作为去重键（deduplication key）。由于投递语义为 at-least-once，同一事件可能被多次推送。接收端应：
  1. 使用 id 作为唯一键进行去重
  2. 在处理前检查该 id 是否已被消费
  3. 确保事件处理逻辑的幂等性

附录 A：快速接入指南

步骤 1：创建 Webhook 端点

curl -X POST https://api.qoder.com/api/v1/cloud/webhook_endpoints \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.example.com/webhooks/qoder",
    "description": "Production webhook",
    "events": ["session.status_idled", "session.thread_idled"]
  }'

步骤 2：实现接收端

在您的服务中实现 Webhook 接收端点，确保：
  1. 解析 JSON Payload，并根据 type 处理对应事件
  2. 使用事件 id 做幂等去重
  3. 返回 200 OK 确认收到
  4. 异步处理业务逻辑（避免超时）

步骤 3：发送测试事件

curl -X POST https://api.qoder.com/api/v1/cloud/webhook_endpoints/{id}/test \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"

步骤 4：验证并上线

确认测试事件接收正常后，即可投入生产使用。

附录 B：最佳实践

实践说明
幂等处理使用事件 id 去重，防止重复消费
快速响应接收端应在 5 秒内返回 2xx，耗时逻辑异步处理
精确订阅仅订阅需要的事件类型，减少不必要的网络开销
监控告警监控 consecutive_fail 指标，及时发现投递异常
快速入门
构建 Agent
配置 Agent 环境
委派任务给 Agent
集成 Agent
管理 Agent 上下文
账户
最佳实践
公告
API 参考