Skip to main content

Webhook

通过 Webhook,在 Session、Agent 等资源变化时接收通知。先注册接收地址并配置验签,再按通知中的资源 ID 查询详情。

注册端点

先准备一个接收通知的 URL:它需要能从公网访问,使用 HTTPS 的 443 端口,并接受 POST 请求。 调用管理 API 时,在 $QODER_ACCESS_TOKEN 中设置个人访问令牌(PAT)或服务账号令牌(SAT)。创建端点后返回的 signing_secret 用于通知验签。 根据资源所在区域设置 QODER_BASE_URL:
区域Base URL
Globalhttps://api.qoder.com/api/v1/cloud
CNhttps://api.qoder.com.cn/api/v1/cloud
将 url 替换为你的接收地址。本例订阅 session.status_idled,在 Agent 等待工具处理或新的用户输入时接收通知。
curl -X POST "$QODER_BASE_URL/webhook_endpoints" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.example.com/webhooks/qoder",
    "description": "Session notifications",
    "events": ["session.status_idled"]
  }'
保存响应中的端点 id,并将其用于后续示例的 $QODER_WEBHOOK_ENDPOINT_ID。signing_secret 只在创建时返回一次,请安全保存。 处理通知前,先按验证签名配置接收端。使用原始请求体验签,并检查时间戳。

处理事件

验签通过后,再解析请求体并处理事件:
  1. 用顶层 id 去重。已经处理过的通知,直接返回 2xx。
  2. 根据 data.type 处理事件,需要详情时按资源查询表调用 GET 接口;删除事件可以直接用于更新本地记录。
  3. 接收端返回 HTTP 200 或其他 2xx 状态码,表示通知已成功接收。
收到 session.status_idled 时,用 data.id 作为 Session ID,通过 GET /sessions/{id}/events 读取 Agent 输出和 session.status_idle 事件(见列出 Session 事件)。根据该流事件的 stop_reason.type 判断下一步操作,常见情况如下:
  • requires_action:需要确认工具调用或提交自定义工具结果。按发送事件中的示例响应相应的工具事件;所需操作全部处理完成后,Agent 恢复运行,并发送 session.status_run_started。
  • end_turn:本轮运行已结束,可以读取输出并判断任务结果。
  • error:本轮因错误停止,读取同一轮的 session.error 事件排查原因。
收到 session.thread_idled 时,读取对应 Thread 的事件,结合 session.thread_status_idle 的 stop_reason.type 和输出判断结果。进入 idle 只表示当前运行已停止或正在等待。 GET /sessions/{id} 可查询 Session 的当前状态。等待工具处理时,该状态仍可能为 running,请结合上述流事件判断需要处理的操作。 通知使用以下 JSON 格式。

业务事件示例

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

字段说明

字段类型说明
idstring通知的唯一 ID,以 whe_ 开头;重试保持不变,与 Webhook-Id 请求头一致
created_atstring事件发生时间,RFC 3339 UTC 格式;重试保持不变
typestring固定值 "event"
dataobject事件类型和资源标识
data.idstring事件对应的资源 ID,查询方式见下表。Thread 事件使用 Session ID,Vault Credential 事件使用 Credential ID
data.typestring事件类型字符串,如 "session.status_idled"、"agent.updated"
data.session_thread_idstring(仅 Thread 事件)所属的 Session Thread ID
data.vault_idstring(仅 Vault Credential 事件)所属的 Vault ID

查询事件对应的资源

data 提供资源标识,不包含资源的完整内容。使用通知中的字段替换下表的路径参数,并沿用管理 API 的 Base URL 和访问令牌。
事件类别GET 路径参数来源
Session/sessions/{id}id = data.id
Session Thread/sessions/{session_id}/threads/{thread_id}session_id = data.id;thread_id = data.session_thread_id
Agent/agents/{id}id = data.id
Deployment/deployments/{id}id = data.id
Deployment Run/deployment_runs/{run_id}run_id = data.id
Environment/environments/{id}id = data.id
Memory Store/memory_stores/{id}id = data.id
Vault/vaults/{id}id = data.id
Vault Credential/vaults/{vault_id}/credentials/{credential_id}vault_id = data.vault_id;credential_id = data.id
读取 Agent 输出时,使用 GET /sessions/{id}/events;Thread 输出使用 GET /sessions/{session_id}/threads/{thread_id}/events。按响应的 next_page 继续读取后续页面,具体参数见Session 事件和Thread 事件。 .deleted 事件表示资源已删除,对应 GET 可能返回 404;直接以删除通知更新本地记录。其他事件查询到的也是资源当前状态,可能已晚于通知发生时的状态。

投递行为

通知以 HTTPS POST 请求发送,请求体为 JSON,每次投递最多等待 30 秒。
  • 重复通知: 同一事件可能到达多次。通知顶层的 id 与 Webhook-Id 相同,重试时保持不变,请用它去重。
  • 订阅范围: 请在触发业务操作前订阅事件。新增订阅只接收之后产生的事件,历史事件不会补发。
  • 到达顺序: 通知可能乱序,例如同一资源的删除通知可能先于归档通知到达。请通过资源查询接口核对当前状态;资源已删除时,按删除通知处理。
  • 重试: 每个事件向每个端点最多投递 3 次。首次失败后等待 5–10 秒重试,再次失败后等待 10–20 秒进行最后一次尝试;等待时间在各区间内随机选择。最终失败的事件不会补发,也不会另行通知投递丢失。
  • 响应处理: 返回任意 2xx 表示已接收。3xx 不会重试;其他非 2xx 响应(包括 4xx、5xx)、连接错误和超时按上述规则重试。
  • 自动禁用: 端点首次返回 3xx,或连接时发现端点地址解析为非公网 IP,会立即禁用。系统不会跟随重定向。端点持续一段时间无法成功接收通知时也会禁用;期间任何一次 2xx 都会清除此前累计的失败时间。
地址变更时,请更新端点的 url。接收服务恢复后,调用 POST /webhook_endpoints/{id}/enable 启用端点。禁用期间产生的事件不会补发。 对于关键业务,定期查询资源状态并与本地记录核对,以处理通知未能送达的情况。

出错怎么办

问题处理方式
管理 API 返回 400按响应说明检查 URL、事件名称、非空订阅列表及 metadata;查询事件记录时使用整数记录 ID,而非 whe_ 通知 ID。
管理 API 返回 401检查 PAT / SAT。认证响应可能使用 code,见错误响应格式。
管理 API 返回 404确认资源 ID、访问令牌及区域一致,资源没有被删除。
创建端点返回 409端点数量已达上限,清理不再使用的端点后重试。此时 error.type 为 invalid_request_error。
接收端验签失败使用创建端点时保存的签名密钥,保留原始请求体,并检查服务器时间。
收不到通知确认端点已启用、事件在业务操作前已订阅、URL 可从公网访问,并检查接收端日志。
端点被自动禁用查看 disabled_reason,修复地址或响应问题后调用 /enable。禁用期间的事件不会补发。
收到重复或乱序通知按通知顶层 id 去重,通过资源 GET 获取当前状态。
需要进一步排查时,保留 request_id(如有)、通知 ID 和接收端日志。业务 API 调用成功,并不代表接收端已经成功处理通知。

支持的事件类型

选择需要订阅的事件,并将表中的完整名称填入 events。支持以下 38 种具名事件,不支持通配符订阅。

Session 事件

部分 Webhook 事件的名称与 Session 事件流不同。例如,事件流中的 session.status_running 和 session.status_idle 分别对应 session.status_run_started 和 session.status_idled。 请求重试耗尽时,本轮运行结束,Session 返回空闲状态;处理错误后可以发送新消息。子 Thread 重试耗尽后也会回到空闲状态,可以继续接收任务。收到 session.status_terminated 时,该 Session 已结束,后续任务需要新建 Session。
事件类型触发条件
session.createdSession 已创建。
session.updatedSession 的属性已更新,例如标题、metadata 或配置。
session.archivedSession 已归档。
session.deletedSession 已永久删除。
session.status_run_startedSession 开始或恢复运行,包括工具操作处理完成或重试后恢复。
session.status_idledAgent 进入空闲状态,例如本轮运行结束、因错误停止,或等待工具确认、自定义工具结果。
session.status_rescheduled发生可重试错误,Session 正在重新调度。
session.status_terminatedSession 已归档并终止。
session.thread_createdSession 中创建了新的子 Thread。
session.thread_idledThread 进入空闲状态,例如任务结束、因错误停止,或等待工具处理。主 Thread 和子 Thread 都可能收到此通知。
session.thread_terminated子 Thread 已归档并终止,或 Advisor 咨询完成后结束。
session.outcome_evaluation_ended一次 Outcome 评估迭代已结束,包括需要继续修改或评估被中断的情况。
收到 session.outcome_evaluation_ended 后,通过 GET /sessions/{id} 的 outcome_evaluations 查看各个 Outcome 的最新评估状态。Outcome 被中断时,result 为 interrupted,即使评估尚未开始也会发送通知。需要查看每轮评估结果时,读取 Session 事件流中的 span.outcome_evaluation_end;在评估开始前中断的记录中,outcome_evaluation_start_id 为空字符串。 同一次运行恢复只产生一个 session.status_run_started 事件,不会按完成的工具操作数分别产生事件。通知可能重复投递,请按处理事件中的方式去重。

Vault 事件

事件类型触发条件
vault.createdVault 已创建。
vault.archivedVault 已归档,其中的每条凭证也会触发 vault_credential.archived。
vault.deletedVault 已删除,其中的每条凭证也会触发 vault_credential.deleted。
vault_credential.created凭证已创建。
vault_credential.archived凭证已归档,可能是单独归档,也可能随所属 Vault 一同归档。
vault_credential.deleted凭证已删除,可能是单独删除,也可能随所属 Vault 一同删除。
vault_credential.refresh_failedmcp_oauth 凭证无法刷新,例如授权失效、刷新配置错误,或 OAuth 服务拒绝刷新请求。
收到通知后,检查 OAuth 授权和刷新配置,必要时重新授权。OAuth 刷新接口返回 4xx(408、429 除外)会触发此事件,即使响应中没有标准 OAuth 错误码。超时、限流、网络错误和 5xx 不触发此事件,可稍后重试。

Agent 事件

这些事件描述 Agent 资源的变化。Agent 的消息和工具调用通过 Session 事件流读取。
事件类型触发条件
agent.createdAgent 已创建。
agent.updatedAgent 的新版本已发布。
agent.archivedAgent 已归档,无法用于创建新的 Session。
agent.deletedAgent 已永久删除。

Deployment 事件

事件类型触发条件
deployment.createdDeployment 已创建。
deployment.updatedDeployment 的属性已更新,例如调度表达式。
deployment.pausedDeployment 已暂停,可能由用户暂停,也可能在首次遇到不可恢复的定时启动错误后自动暂停,例如引用的 Environment 已归档或服务账号绑定失效。临时网络故障、限流等可恢复错误不会因此自动暂停。
deployment.unpausedDeployment 已恢复调度。
deployment.archivedDeployment 已归档。
收到 deployment.paused 后,通过 GET /deployments/{id} 的 paused_reason 查看原因。修复问题后可恢复调度。归档主 Agent 时,其关联 Deployment 会一同归档并发送 deployment.archived。删除主 Agent 后,仍在调度的 Deployment 会在下次触发时归档,不再创建该次 Run;没有后续调度的 Deployment 请手动归档。

Deployment Run 事件

定时运行和手动运行都会发送这些事件。data.id 是本次运行的 ID。通过 GET /deployment_runs/{run_id} 获取 session_id 后,可按处理事件中的说明查询 Session 状态和输出。
事件类型触发条件
deployment_run.started定时运行已开始尝试创建 Session。手动运行保留兼容行为,在 Session 创建后发送。
deployment_run.succeeded本次运行已创建 Session;这不代表 Session 内的任务已完成或成功。
deployment_run.failed本次运行未能创建 Session。查询 Deployment Run 可查看错误详情。
定时运行在尝试创建 Session 前发送 deployment_run.started,随后发送 deployment_run.succeeded 或 deployment_run.failed,两条通知的 data.id 相同。手动运行创建 Session 成功时发送 started 和 succeeded;创建失败时只发送 failed。通知可能乱序或重复,请分别处理并按通知 ID 去重。 Session 创建后的执行超时、错误或完成,通过 Session 事件和对应的状态查询接口跟踪,不会再改变本次 Run 的创建结果通知。

Environment 事件

事件类型触发条件
environment.createdEnvironment 已创建。
environment.updatedEnvironment 的字段发生变化;未修改任何字段时不发送通知。
environment.archivedEnvironment 已归档。
environment.deletedEnvironment 已删除。

Memory Store 事件

事件类型触发条件
memory_store.createdMemory Store 已创建,包括用户创建和平台克隆。
memory_store.archivedMemory Store 已归档。
memory_store.deletedMemory Store 已删除。
Memory Store 删除时,其 Memory 和版本一同删除,不逐条发送 Memory 通知。

API 参考

本节介绍端点管理和事件记录查询接口。路径中的 {id} 为端点 ID;/webhook_events/{id} 使用事件记录 ID。 Base URL、访问令牌和端点 ID 的设置见注册端点。下列接口均需要 Authorization: Bearer $QODER_ACCESS_TOKEN。

POST /webhook_endpoints

创建一个新的 Webhook 端点。 请求参数:
字段类型必填说明
urlstring是接收通知的 URL,必须使用公网可访问的 HTTPS 地址,端口为 443
descriptionstring否端点描述,便于管理识别
metadataobject否自定义字符串键值对,默认 {};最多 16 项,键最多 64 个字符,值最多 512 个字符
eventsstring[]是订阅的事件类型列表,至少包含一项;使用事件类型中的完整名称,不支持通配符
响应: 201 Created
{
  "id": "700e7789-edab-41cb-b60a-210d0df38ab6",
  "url": "https://your-app.example.com/webhooks/qoder",
  "description": "quickstart demo",
  "events": ["session.status_idled", "session.thread_idled"],
  "metadata": {},
  "active": true,
  "signing_secret": "whsec_O30snlHwqEFj1b4Hwq+RONpG4LV8HzmC6l0MRrmPc1E=",
  "created_at": "2026-07-02T18:17:30.069191+08:00"
}
注意: signing_secret 仅在创建时返回一次,请安全保存。用它验签的方法见验证签名。
状态码:
状态码说明
201创建成功
400请求参数无效(如 URL 格式无效、events 为空、事件名称格式不合法或 metadata 不符合约束)
401未授权,Token 无效或过期
409超过每用户可创建的端点数量上限,error.type 为 invalid_request_error

GET /webhook_endpoints

获取当前账户下的 Webhook 端点列表。 请求参数:
参数类型必填说明
limitinteger否返回条数,默认 50,最大 100
响应: 200 OK
{
  "data": [
    {
      "id": "700e7789-edab-41cb-b60a-210d0df38ab6",
      "url": "https://your-app.example.com/webhooks/qoder",
      "description": "prod app hook",
      "events": ["session.status_idled", "session.thread_idled"],
      "metadata": {},
      "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端点描述
metadataobject自定义字符串键值对
eventsstring[]订阅的事件类型列表
activeboolean是否启用。被自动禁用时为 false
disabled_reasonstring自动禁用的原因,存在时返回
consecutive_failinteger连续投递失败次数
last_success_atstring最近一次成功投递时间(RFC 3339),无成功记录时不返回
last_failure_atstring最近一次投递失败时间(RFC 3339),无失败记录时不返回
created_atstring创建时间(RFC 3339)
updated_atstring最近更新时间(RFC 3339)

GET /webhook_endpoints/{id}

获取指定 Webhook 端点的详细信息。 路径参数:
参数类型说明
idstringWebhook 端点 ID
响应: 200 OK 返回单个端点对象,结构与列表接口中的元素一致。 状态码:
状态码说明
200成功
404端点不存在

PUT /webhook_endpoints/{id}

更新指定 Webhook 端点的配置。只需提交要修改的字段,未提交的字段保持原值。 路径参数:
参数类型说明
idstringWebhook 端点 ID
请求参数:
字段类型必填说明
urlstring否更新接收地址,必须使用公网可访问的 HTTPS 地址,端口为 443
descriptionstring否更新端点描述
metadataobject否按键合并,值为 null 时删除该键;{} 不清空原值。合并后遵守创建接口的数量和长度限制
eventsstring[]否替换订阅的事件类型列表,至少包含一项
响应: 200 OK 返回更新后的完整端点对象。 状态码:
状态码说明
200更新成功
400请求参数无效
404端点不存在
示例:
curl -X PUT "$QODER_BASE_URL/webhook_endpoints/$QODER_WEBHOOK_ENDPOINT_ID" \
  -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端点不存在

POST /webhook_endpoints/{id}/enable

启用指定 Webhook 端点,恢复接收新事件。禁用期间产生的事件不会补发。 路径参数:
参数类型说明
idstringWebhook 端点 ID
请求参数: 无 响应: 200 OK 返回启用后的端点对象(active: true)。 状态码:
状态码说明
200启用成功
404端点不存在

POST /webhook_endpoints/{id}/disable

禁用指定 Webhook 端点,停止接收新事件通知,保留端点配置。已开始发送的通知仍可能送达。 路径参数:
参数类型说明
idstringWebhook 端点 ID
请求参数: 无 响应: 200 OK 返回禁用后的端点对象(active: false)。 状态码:
状态码说明
200禁用成功
404端点不存在

GET /webhook_events

列出已产生的 Webhook 事件记录,用于审计和排查。 返回事件记录,不包含投递结果。需要确认通知是否收到或处理成功时,请查看接收服务的日志。 请求参数:
参数类型必填说明
limitinteger否返回条数,默认 50,最大 100
响应: 200 OK 响应的 data 字段包含按产生时间倒序排列的事件记录;无记录时为 null。每条记录的主要字段如下:
字段类型说明
idinteger事件记录 ID,用于查询单条记录
event_typestring事件类型,如 session.status_idled
payloadobject通知的 JSON 内容;其中 payload.id 是 whe_ 开头的通知 ID
created_atstring记录创建时间(RFC 3339)

GET /webhook_events/{id}

获取单个 Webhook 事件记录的详细信息。 路径参数:
参数类型说明
idinteger事件记录 ID,取自列表响应的 id;通知中的 whe_ ID 不用于此接口
响应: 200 OK 返回单条事件记录,字段与列表接口中的记录一致。 状态码:
状态码说明
200成功
400id 不是有效的 64 位有符号整数
404事件不存在

错误响应格式

请求参数无效等 API 错误使用以下格式。例如,事件名含空格时返回 400:
{
  "error": {
    "message": "Invalid event type: session idled",
    "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"
根据 HTTP 状态码和错误分类处理,message 用于说明原因,不应作为固定标识。排查步骤见出错怎么办。 认证失败时,响应体可能由网关返回,不使用上述 error.type 结构。例如,缺少 Authorization 时返回 HTTP 401:
{
  "code": "TOKEN_INVALID",
  "message": "missing authorization token",
  "timestamp": "1792982170292"
}
收到 401 时,先检查访问令牌,再根据实际响应读取 code 或 error.type。

验证签名

使用 Standard Webhooks 官方库验证通知,无需自行实现签名算法。将创建端点时保存的完整 signing_secret 设置为环境变量 QODER_WEBHOOK_SIGNING_SECRET,保留 whsec_ 前缀。 verify() 验证签名和时间戳,通过后返回解析后的事件;签名无效或时间戳与当前时间相差超过 5 分钟时会抛出异常。必须传入原始请求体,不能先解析 JSON 再重新序列化。

请求头

每次投递包含以下 HTTP 请求头:
Header值 / 说明
Content-Typeapplication/json; charset=utf-8
User-AgentQoderCloudAgents-Webhook/1.0
Webhook-Id通知 ID,与请求体顶层的 id 相同;重试时不变,用于去重
Webhook-Timestamp本次签名的 Unix 时间戳(秒),重试时重新生成。业务事件发生时间见 Payload 的 created_at
Webhook-Signature本次投递的签名值
Webhook-Event-Type事件类型,与 data.type 一致
请求头名称不区分大小写,直接将接收到的请求头传给验签库。

示例:Node.js

安装依赖:
npm install express standardwebhooks
将以下代码保存为 receiver.cjs,运行 node receiver.cjs。此路由应在 express.json() 等 JSON 解析中间件之前注册。
const express = require('express');
const { Webhook } = require('standardwebhooks');

const app = express();
const webhook = new Webhook(process.env.QODER_WEBHOOK_SIGNING_SECRET);

app.post('/webhooks/qoder', express.raw({ type: 'application/json' }), async (req, res) => {
  let event;
  try {
    event = webhook.verify(req.body, req.headers);
  } catch {
    return res.status(400).send('Invalid webhook');
  }

  try {
    // 在这里按 event.id 去重并处理事件;处理失败应返回 5xx。
    if (event.data.type === 'session.status_idled') {
      // 使用 event.data.id 查询 Session 及其事件,执行你的业务逻辑。
    }
    return res.sendStatus(200);
  } catch {
    return res.sendStatus(500);
  }
});

app.listen(3000);

示例:Python

安装依赖:
pip install flask standardwebhooks
将以下代码保存为 receiver.py,运行 flask --app receiver run --port 3000。
import os

from flask import Flask, request
from standardwebhooks.webhooks import Webhook, WebhookVerificationError

app = Flask(__name__)
webhook = Webhook(os.environ["QODER_WEBHOOK_SIGNING_SECRET"])


@app.post("/webhooks/qoder")
def receive_webhook():
    try:
        event = webhook.verify(request.get_data(), dict(request.headers))
    except (WebhookVerificationError, ValueError):
        return "Invalid webhook", 400

    # 在这里按 event["id"] 去重并处理事件;处理异常时 Flask 返回 500。
    if event["data"]["type"] == "session.status_idled":
        # 使用 event["data"]["id"] 查询 Session 及其事件,执行你的业务逻辑。
        pass
    return "", 200
以上示例展示接收和验签流程,请在注释位置补充去重和业务处理。实际接入时,通过公网 HTTPS 443 地址将请求转发到接收服务;本地监听地址不能直接注册为端点。