Webhooks - Qoder

概述

Webhook 是 Qoder Cloud Agents 提供的事件驱动推送机制。当 Agent、Session 等资源发生生命周期变化时，系统以 HTTP POST 方式将结构化事件推送到开发者注册的 URL，无需轮询即可实时获取状态变更。 核心特性：

事件驱动推送 — 资源状态变更时主动通知，无需客户端轮询
信封结构 — 统一的 BetaWebhookEvent { id, created_at, data, type:"event" } 格式
投递语义 — at-least-once 保证；HMAC-SHA256 签名验证；指数退避重试
通配符订阅 — 使用 * 订阅所有事件类型，简化集成配置

适用场景：

场景	说明
异步任务完成通知	Session 执行完毕后触发下游流程
Agent 配置变更审计	记录 Agent 创建/更新/删除操作
多 Agent 协作编排	Thread 状态变更驱动子任务调度
运维监控告警	连续失败计数超阈值时告警

Domain Types

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

Session 生命周期事件

Webhook Session Created Event Data

WebhookSessionCreatedEventData object { id, type }
- id: string 触发事件的 Session ID。
- type: "session.created"
  - "session.created"
  Session 被成功创建时触发。通过 POST /sessions 接口创建 Session 后，系统立即发送此事件。

Webhook Session Updated Event Data

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

Webhook Session Archived Event Data

WebhookSessionArchivedEventData object { id, type }
- id: string 触发事件的 Session ID。
- type: "session.archived"
  - "session.archived"
  Session 被归档时触发。归档后 Session 不再接受新消息，但历史数据仍可查询。

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 生命周期事件

Agent 事件在基础字段之外额外携带 version 字段，标识 Agent 的配置版本号。

Webhook Agent Created Event Data

WebhookAgentCreatedEventData object { id, type, version }
- id: string 触发事件的 Agent ID。
- type: "agent.created"
  - "agent.created"
  Agent 被成功创建时触发。通过 POST /agents 接口创建 Agent 后，系统发送此事件。
- version: integer Agent 版本号。首次创建时为 1。

Webhook Agent Updated Event Data

WebhookAgentUpdatedEventData object { id, type, version }
- id: string 触发事件的 Agent ID。
- type: "agent.updated"
  - "agent.updated"
  Agent 配置被更新时触发。每次更新 version 递增。
- version: integer Agent 版本号。

Webhook Agent Archived Event Data

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

Webhook Agent Deleted Event Data

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

Webhook Endpoint API

管理 Webhook 端点的 CRUD 接口。通过这些接口可以创建、查询、更新、删除 Webhook 端点，以及发送测试事件和控制端点的启用/禁用状态。 Base URL：

区域	地址
Global	`https://api.qoder.com/api/v1/cloud`
CN	`https://api.qoder.com.cn/api/v1/cloud`

认证方式： 所有接口均需要在请求头中携带 Personal Access Token：

Authorization: Bearer $PAT

POST /webhook_endpoints

创建一个新的 Webhook 端点。 请求参数：

字段	类型	必填	说明
`url`	string	是	接收事件推送的 HTTP 或 HTTPS URL（生产环境强烈建议使用 HTTPS）
`description`	string	否	端点描述，便于管理识别
`events`	string[]	是	订阅的事件类型列表，支持 `*` 通配符

响应： 201 Created

{
  "id": "5fc05310-4d9c-447e-a4b8-f124f17e1ff0",
  "url": "https://webhook.site/your-unique-path",
  "description": "quickstart demo",
  "events": ["*"],
  "active": true,
  "signing_secret": "whsec_BfJDodFEzmkdjAUf19-_XthSq6KbPKmRjfm9KFWMIuk",
  "signing_secret_version": 1,
  "created_at": "2026-07-02T18:17:30.069191+08:00"
}

注意： signing_secret 仅在创建时返回一次，请妥善保存。后续查询接口不会再次返回此字段。

状态码：

状态码	说明
201	创建成功
400	请求参数无效（如 URL 格式错误、事件类型不合法）
401	未授权，Token 无效或过期
422	语义错误（如 URL 重复注册）

示例：

curl -X POST https://api.qoder.com/api/v1/cloud/webhook_endpoints \
  -H "Authorization: Bearer $PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://webhook.site/your-unique-path",
    "description": "quickstart demo",
    "events": ["*"]
  }'

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.created", "session.thread_idled"],
      "active": true,
      "signing_secret_version": 1,
      "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"
    }
  ]
}

响应字段说明：

字段	类型	说明
`id`	string	端点唯一标识
`url`	string	接收事件的 URL
`description`	string	端点描述
`events`	string[]	订阅的事件类型列表
`active`	boolean	是否启用
`signing_secret_version`	integer	签名密钥版本号
`consecutive_fail`	integer	连续投递失败次数
`last_success_at`	string	最近一次成功投递时间（RFC 3339）
`last_failure_at`	string	最近一次投递失败时间（RFC 3339），无失败记录时为 null
`created_at`	string	创建时间（RFC 3339）
`updated_at`	string	最近更新时间（RFC 3339）

示例：

curl https://api.qoder.com/api/v1/cloud/webhook_endpoints \
  -H "Authorization: Bearer $PAT"

GET /webhook_endpoints/{id}

获取指定 Webhook 端点的详细信息。 路径参数：

参数	类型	说明
`id`	string	Webhook 端点 ID

响应： 200 OK 返回单个端点对象，结构与列表接口中的元素一致。 状态码：

状态码	说明
200	成功
404	端点不存在

示例：

curl https://api.qoder.com/api/v1/cloud/webhook_endpoints/700e7789-edab-41cb-b60a-210d0df38ab6 \
  -H "Authorization: Bearer $PAT"

PUT /webhook_endpoints/{id}

更新指定 Webhook 端点的配置。 路径参数：

参数	类型	说明
`id`	string	Webhook 端点 ID

请求参数：

字段	类型	必填	说明
`url`	string	否	更新接收事件推送的 URL
`description`	string	否	更新端点描述
`events`	string[]	否	更新订阅的事件类型列表

响应： 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 $PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["session.created", "session.status_idled", "agent.updated"],
    "description": "updated prod hook"
  }'

DELETE /webhook_endpoints/{id}

永久删除指定的 Webhook 端点。删除后所有未投递的事件将被丢弃。 路径参数：

参数	类型	说明
`id`	string	Webhook 端点 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 $PAT"

POST /webhook_endpoints/{id}/test

向指定端点发送一个测试事件，用于验证端点连通性和签名验证逻辑。 路径参数：

参数	类型	说明
`id`	string	Webhook 端点 ID

请求参数： 无 响应： 202 Accepted

{"event_id": 433, "delivery_rows": 2}

响应字段说明：

字段	类型	说明
`event_id`	integer	测试事件的内部 ID
`delivery_rows`	integer	事件发布的消息分区数

状态码：

状态码	说明
202	测试事件已发送
404	端点不存在

示例：

curl -X POST https://api.qoder.com/api/v1/cloud/webhook_endpoints/700e7789-edab-41cb-b60a-210d0df38ab6/test \
  -H "Authorization: Bearer $PAT"

POST /webhook_endpoints/{id}/enable

启用一个被禁用的 Webhook 端点。启用后端点将重新接收事件推送。 路径参数：

参数	类型	说明
`id`	string	Webhook 端点 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 $PAT"

POST /webhook_endpoints/{id}/disable

禁用一个 Webhook 端点。禁用后端点将停止接收事件推送，但不会被删除。 路径参数：

参数	类型	说明
`id`	string	Webhook 端点 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 $PAT"

GET /webhook_events

列出 Webhook 事件投递记录，用于审计和排查。 请求参数： 无 响应： 200 OK 返回事件列表，包含事件的投递状态、时间戳等信息。 示例：

curl https://api.qoder.com/api/v1/cloud/webhook_events \
  -H "Authorization: Bearer $PAT"

GET /webhook_events/{id}

获取单个 Webhook 事件的详细信息。 路径参数：

参数	类型	说明
`id`	string	Webhook 事件 ID

响应： 200 OK 状态码：

状态码	说明
200	成功
404	事件不存在

示例：

curl https://api.qoder.com/api/v1/cloud/webhook_events/433 \
  -H "Authorization: Bearer $PAT"

错误响应格式

所有接口在遇到错误时，返回统一的错误结构：

{
  "error": {
    "message": "Unknown event type: agent.updated",
    "type": "invalid_request_error"
  },
  "request_id": "cc865161-b25d-4d68-bad5-bf0363f6e0f9",
  "type": "error"
}

错误字段说明：

字段	类型	说明
`error.message`	string	人类可读的错误描述
`error.type`	string	错误分类（如 `invalid_request_error`、`not_found_error`）
`request_id`	string	请求追踪 ID，用于排查问题时提供给支持团队
`type`	string	固定值 `"error"`

注意： 鉴权层（如 Token 无效或缺失）返回的 401 响应可能不遵循上述业务错误结构，而是由网关直接返回。

Webhook Delivery（投递机制）

投递方式

系统通过 HTTP POST 将事件推送到注册的 URL，请求格式如下：

Method: POST
Content-Type: application/json
Body: JSON 格式的信封结构（详见信封结构详解）

请求头

每次投递包含以下 HTTP 请求头：

Header	说明
`Content-Type`	`application/json`
`User-Agent`	`QoderCloudAgents-Webhook/1.0`
`Webhook-Signature`	HMAC-SHA256 签名，格式为 `t=<unix_epoch>,v1=<hmac_sha256_hex>`

签名验证

为确保事件来源的真实性和数据完整性，每次投递都携带 HMAC-SHA256 签名。开发者应在接收端验证签名后再处理事件。 签名格式：

t=1719907336,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8f9

签名算法：

signature = HMAC_SHA256(signing_secret, "<t>.<raw_body>")

其中：

signing_secret — 创建端点时返回的密钥（whsec_ 前缀）
t — 签名时的 Unix 时间戳（秒）
raw_body — 请求体的原始字节内容（未经解析）

验证步骤：

从 Webhook-Signature Header 中提取 t 和 v1
检查时间戳是否在容忍窗口内（建议 600 秒），防止重放攻击
使用 signing_secret 对 "<t>.<raw_body>" 计算 HMAC-SHA256
将计算结果与 v1 进行恒时比较（timing-safe comparison）

签名验证代码示例

Node.js：

const crypto = require('node:crypto');

function verifyWebhook(secret, rawBody, header, toleranceSec = 600) {
  const parts = Object.fromEntries(
    header.split(',').map(kv => kv.split('=').map(s => s.trim()))
  );
  const ts = parseInt(parts.t, 10);
  if (Math.abs(Date.now() / 1000 - ts) > toleranceSec) return false;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${ts}.${rawBody}`)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(parts.v1, 'hex')
  );
}

Python：

import hmac, hashlib, time

def verify_webhook(secret: bytes, raw_body: bytes, header: str, tolerance_sec: int = 600) -> bool:
    parts = dict(kv.split("=", 1) for kv in header.split(","))
    ts = int(parts["t"])
    if abs(time.time() - ts) > tolerance_sec:
        return False
    signed_payload = f"{ts}.".encode() + raw_body
    expected = hmac.new(secret, signed_payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])

Go：

func verifyWebhook(secret, rawBody []byte, header string, toleranceSec int64) bool {
    var ts int64; var v1 string
    for _, kv := range strings.Split(header, ",") {
        kv = strings.TrimSpace(kv)
        if strings.HasPrefix(kv, "t=") { ts, _ = strconv.ParseInt(kv[2:], 10, 64) }
        if strings.HasPrefix(kv, "v1=") { v1 = kv[3:] }
    }
    if ts == 0 || v1 == "" { return false }
    if diff := time.Now().Unix() - ts; diff > toleranceSec || diff < -toleranceSec { return false }
    mac := hmac.New(sha256.New, secret)
    fmt.Fprintf(mac, "%d.", ts)
    mac.Write(rawBody)
    return hmac.Equal([]byte(hex.EncodeToString(mac.Sum(nil))), []byte(v1))
}

重试策略

当投递失败时，系统采用指数退避策略进行重试：

尝试次数	延迟	说明
第 1 次	立即	首次投递
第 2 次	1 秒	第一次重试
第 3 次	5 秒	第二次重试
第 4 次	30 秒	最终重试

共计 4 次尝试（1 次投递 + 3 次重试）。全部失败后事件进入死信队列。

响应码处理

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

自动降级

当某个端点的 consecutive_fail 计数超过 20 时，系统将触发降级警告。建议开发者监控此指标，并在持续失败时检查：

端点 URL 是否可达
SSL 证书是否有效
服务端是否正常响应
签名验证逻辑是否存在 Bug

Supported Event Types（完整清单）

事件类型总览

事件类型	状态	data 额外字段	触发条件
`session.created`	✅ 已实现	—	POST /sessions 成功创建 Session
`session.updated`	✅ 已实现	—	Session 元数据被修改
`session.archived`	✅ 已实现	—	Session 被归档
`session.deleted`	✅ 已实现	—	Session 被永久删除
`session.status_run_started`	✅ 已实现	—	Agent 开始一轮运行
`session.status_idled`	✅ 已实现	—	Turn 执行完成，回到 idle 状态
`session.thread_created`	✅ 已实现	`session_thread_id`	新的 Session Thread 被创建
`session.thread_idled`	✅ 已实现	`session_thread_id`	Thread 执行结束进入 idle
`session.thread_terminated`	✅ 已实现	`session_thread_id`	Thread 被终止
`agent.created`	✅ 已实现	`version`	POST /agents 创建 Agent
`agent.updated`	✅ 已实现	`version`	Agent 配置被更新
`agent.archived`	✅ 已实现	`version`	Agent 被归档
`agent.deleted`	✅ 已实现	`version`	Agent 被删除
`session.pending`	🔜 白名单已注册	—	Session 等待调度
`session.running`	🔜 白名单已注册	—	Session 正在运行
`session.idled`	🔜 白名单已注册	—	Session 进入 idle
`session.requires_action`	🔜 白名单已注册	—	Session 需要人工介入
`session.status_run_failed`	🔜 白名单已注册	—	运行失败
`session.status_terminated`	🔜 白名单已注册	—	Session 被终止
`session.status_rescheduled`	🔜 白名单已注册	—	Session 被重新调度
`session.status_paused_pending_input`	🔜 白名单已注册	—	暂停等待用户输入
`session.status_paused_pending_approval`	🔜 白名单已注册	—	暂停等待审批
`session.status_paused_user_intervention`	🔜 白名单已注册	—	暂停等待人工干预
`session.outcome_evaluation_started`	🔜 白名单已注册	—	结果评估开始
`session.outcome_evaluation_ended`	🔜 白名单已注册	—	结果评估结束
`vault.created`	🔜 白名单已注册	—	密钥库创建
`vault.deleted`	🔜 白名单已注册	—	密钥库删除
`vault.updated`	🔜 白名单已注册	—	密钥库更新
`vault_credential.created`	🔜 白名单已注册	—	凭据创建
`vault_credential.updated`	🔜 白名单已注册	—	凭据更新
`vault_credential.deleted`	🔜 白名单已注册	—	凭据删除
`vault_credential.shared`	🔜 白名单已注册	—	凭据共享
`vault_credential.revoked`	🔜 白名单已注册	—	凭据撤销
`deployment.created`	📋 规划中	—	部署创建
`deployment.updated`	📋 规划中	—	部署更新
`deployment.archived`	📋 规划中	—	部署归档
`deployment.deleted`	📋 规划中	—	部署删除
`deployment.paused`	📋 规划中	—	部署暂停
`deployment.unpaused`	📋 规划中	—	部署恢复
`deployment_run.started`	📋 规划中	—	部署运行开始
`deployment_run.failed`	📋 规划中	—	部署运行失败
`deployment_run.succeeded`	📋 规划中	—	部署运行成功
`environment.created`	📋 规划中	—	环境创建
`environment.updated`	📋 规划中	—	环境更新
`environment.archived`	📋 规划中	—	环境归档
`environment.deleted`	📋 规划中	—	环境删除
`memory_store.created`	📋 规划中	—	记忆存储创建
`memory_store.archived`	📋 规划中	—	记忆存储归档
`memory_store.deleted`	📋 规划中	—	记忆存储删除

特殊事件类型

事件类型	说明
`*`	通配符，订阅所有事件类型。在创建端点时使用 `["*"]` 可接收全部事件推送
`webhook.test`	内部测试事件，通过 `POST /webhook_endpoints/{id}/test` 触发

状态标记说明

标记	含义
✅ 已实现	系统中存在完整的事件触发点，可正常订阅和接收
🔜 白名单已注册	事件类型已在验证白名单中注册（可用于 `events` 字段），但暂无触发点
📋 规划中	事件类型已在 API 设计层面完成定义，尚未注册到白名单

信封结构详解

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

基础信封结构

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

Thread 事件信封

Thread 事件的 data 中额外包含 session_thread_id 字段：

{
  "id": "whevt_a1b2c3d4e5f67890",
  "created_at": "2026-07-02T10:02:17Z",
  "type": "event",
  "data": {
    "id": "sess_019f224773fe71d79c5869bd089d159c",
    "type": "session.thread_idled",
    "session_thread_id": "sthread_019f224..."
  }
}

Agent 事件信封

Agent 事件的 data 中额外包含 version 字段：

{
  "id": "whevt_a1b2c3d4e5f67890",
  "created_at": "2026-07-02T10:02:16Z",
  "type": "event",
  "data": {
    "id": "agent_019f224773fe71d7...",
    "type": "agent.created",
    "version": 1
  }
}

字段说明

字段	类型	说明
`id`	string	事件唯一标识。格式为 `whevt_` + 唯一标识符，由事件的 idempotency key 确定性生成
`created_at`	string	事件创建时间，RFC 3339 UTC 格式
`type`	string	固定值 `"event"`，标识这是一个事件信封
`data`	object	事件负载，包含触发资源的信息
`data.id`	string	触发事件的资源 ID（Session ID 或 Agent ID）
`data.type`	string	事件类型字符串，如 `"session.created"`、`"agent.updated"`
`data.session_thread_id`	string	（仅 Thread 事件）所属的 Session Thread ID
`data.version`	integer	（仅 Agent 事件）Agent 配置版本号

幂等性处理

信封中的 id 字段可作为去重键（deduplication key）。由于投递语义为 at-least-once，同一事件可能被多次推送。接收端应：

使用 id 作为唯一键进行去重
在处理前检查该 id 是否已被消费
确保事件处理逻辑的幂等性

规划中的事件（Coming Soon）

以下事件类型已在 API 设计层面完成对齐，将随各资源功能上线后逐步开放。具体时间线视产品需求确定。

deployment.* （部署生命周期，6 个事件）

事件类型	触发条件
`deployment.created`	新部署被创建
`deployment.updated`	部署配置被更新
`deployment.archived`	部署被归档
`deployment.deleted`	部署被删除
`deployment.paused`	部署被暂停（停止触发新运行）
`deployment.unpaused`	部署被恢复（重新开始触发运行）

deployment_run.* （部署运行状态，3 个事件）

事件类型	触发条件
`deployment_run.started`	一次部署运行开始执行
`deployment_run.failed`	部署运行失败
`deployment_run.succeeded`	部署运行成功完成

environment.* （环境管理，4 个事件）

事件类型	触发条件
`environment.created`	运行环境被创建
`environment.updated`	环境配置被更新
`environment.archived`	环境被归档
`environment.deleted`	环境被删除

memory_store.* （记忆存储，3 个事件）

事件类型	触发条件
`memory_store.created`	记忆存储实例被创建
`memory_store.archived`	记忆存储被归档
`memory_store.deleted`	记忆存储被删除

vault.* （密钥库，3 个事件）

事件类型	触发条件
`vault.created`	密钥库被创建
`vault.updated`	密钥库配置被更新
`vault.deleted`	密钥库被删除

vault_credential.* （凭据管理，5 个事件）

事件类型	触发条件
`vault_credential.created`	新凭据被添加到密钥库
`vault_credential.updated`	凭据信息被更新
`vault_credential.deleted`	凭据被删除
`vault_credential.shared`	凭据被共享给其他 Agent
`vault_credential.revoked`	凭据的共享权限被撤销

附录 A：快速接入指南

步骤 1：创建 Webhook 端点

curl -X POST https://api.qoder.com/api/v1/cloud/webhook_endpoints \
  -H "Authorization: Bearer $PAT" \
  -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：保存 signing_secret

从创建响应中获取 signing_secret 并安全存储，后续验证签名时使用。

步骤 3：实现接收端

在您的服务中实现 Webhook 接收端点，确保：

验证 Webhook-Signature 签名
使用事件 id 做幂等去重
返回 200 OK 确认收到
异步处理业务逻辑（避免超时）

步骤 4：发送测试事件

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

步骤 5：验证并上线

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

附录 B：最佳实践

实践	说明
签名验证	始终验证 `Webhook-Signature`，拒绝无效请求
幂等处理	使用事件 `id` 去重，防止重复消费
快速响应	接收端应在 5 秒内返回 2xx，耗时逻辑异步处理
时间戳校验	拒绝超过容忍窗口的事件，防止重放攻击
精确订阅	仅订阅需要的事件类型，减少不必要的网络开销
监控告警	监控 `consecutive_fail` 指标，及时发现投递异常

增量流式访问 GitHub

​概述

​Domain Types

​Session 生命周期事件

​Webhook Session Created Event Data

​Webhook Session Updated Event Data

​Webhook Session Archived Event Data

​Webhook Session Deleted Event Data

​Session 状态事件

​Webhook Session Status Run Started Event Data

​Webhook Session Status Idled Event Data

​Session Thread 事件

​Webhook Session Thread Created Event Data

​Webhook Session Thread Idled Event Data

​Webhook Session Thread Terminated Event Data

​Agent 生命周期事件

​Webhook Agent Created Event Data

​Webhook Agent Updated Event Data

​Webhook Agent Archived Event Data

​Webhook Agent Deleted Event Data

​Webhook Endpoint API

​POST /webhook_endpoints

​GET /webhook_endpoints

​GET /webhook_endpoints/{id}

​PUT /webhook_endpoints/{id}

​DELETE /webhook_endpoints/{id}

​POST /webhook_endpoints/{id}/test

​POST /webhook_endpoints/{id}/enable

​POST /webhook_endpoints/{id}/disable

​GET /webhook_events

​GET /webhook_events/{id}

​错误响应格式

​Webhook Delivery（投递机制）

​投递方式

​请求头

​签名验证

​签名验证代码示例

​重试策略

​响应码处理

​自动降级

​Supported Event Types（完整清单）

​事件类型总览

​特殊事件类型

​状态标记说明

​信封结构详解

​基础信封结构

​Thread 事件信封

​Agent 事件信封

​字段说明

​幂等性处理

​规划中的事件（Coming Soon）

​deployment.* （部署生命周期，6 个事件）

​deployment_run.* （部署运行状态，3 个事件）

​environment.* （环境管理，4 个事件）

​memory_store.* （记忆存储，3 个事件）

​vault.* （密钥库，3 个事件）

​vault_credential.* （凭据管理，5 个事件）

​附录 A：快速接入指南

​步骤 1：创建 Webhook 端点

​步骤 2：保存 signing_secret

​步骤 3：实现接收端

​步骤 4：发送测试事件

​步骤 5：验证并上线

​附录 B：最佳实践

概述

Domain Types

Session 生命周期事件

Webhook Session Created Event Data

Webhook Session Updated Event Data

Webhook Session Archived Event Data

Webhook Session Deleted Event Data

Session 状态事件

Webhook Session Status Run Started Event Data

Webhook Session Status Idled Event Data

Session Thread 事件

Webhook Session Thread Created Event Data

Webhook Session Thread Idled Event Data

Webhook Session Thread Terminated Event Data

Agent 生命周期事件

Webhook Agent Created Event Data

Webhook Agent Updated Event Data

Webhook Agent Archived Event Data

Webhook Agent Deleted Event Data

Webhook Endpoint API

POST /webhook_endpoints

GET /webhook_endpoints

GET /webhook_endpoints/{id}

PUT /webhook_endpoints/{id}

DELETE /webhook_endpoints/{id}

POST /webhook_endpoints/{id}/test

POST /webhook_endpoints/{id}/enable

POST /webhook_endpoints/{id}/disable

GET /webhook_events

GET /webhook_events/{id}

错误响应格式

Webhook Delivery（投递机制）

投递方式

请求头

签名验证

签名验证代码示例

重试策略

响应码处理

自动降级

Supported Event Types（完整清单）

事件类型总览

特殊事件类型

状态标记说明

信封结构详解

基础信封结构

Thread 事件信封

Agent 事件信封

字段说明

幂等性处理

规划中的事件（Coming Soon）

deployment.* （部署生命周期，6 个事件）

deployment_run.* （部署运行状态，3 个事件）

environment.* （环境管理，4 个事件）

memory_store.* （记忆存储，3 个事件）

vault.* （密钥库，3 个事件）

vault_credential.* （凭据管理，5 个事件）

附录 A：快速接入指南

步骤 1：创建 Webhook 端点

步骤 2：保存 signing_secret

步骤 3：实现接收端

步骤 4：发送测试事件

步骤 5：验证并上线

附录 B：最佳实践