通过 Webhook,在 Session、Agent 等资源变化时接收通知。先注册接收地址并配置验签,再按通知中的资源 ID 查询详情。
先准备一个接收通知的 URL:它需要能从公网访问,使用 HTTPS 的 443 端口,并接受 POST 请求。
调用管理 API 时,在
将
保存响应中的端点
验签通过后,再解析请求体并处理事件:
读取 Agent 输出时,使用
通知以 HTTPS POST 请求发送,请求体为 JSON,每次投递最多等待 30 秒。
需要进一步排查时,保留
选择需要订阅的事件,并将表中的完整名称填入
部分 Webhook 事件的名称与 Session 事件流不同。例如,事件流中的
收到
收到通知后,检查 OAuth 授权和刷新配置,必要时重新授权。OAuth 刷新接口返回
这些事件描述 Agent 资源的变化。Agent 的消息和工具调用通过 Session 事件流读取。
收到
定时运行和手动运行都会发送这些事件。
定时运行在尝试创建 Session 前发送
Memory Store 删除时,其 Memory 和版本一同删除,不逐条发送 Memory 通知。
本节介绍端点管理和事件记录查询接口。路径中的
创建一个新的 Webhook 端点。
请求参数:
响应:
获取当前账户下的 Webhook 端点列表。
请求参数:
响应:
响应字段说明:
获取指定 Webhook 端点的详细信息。
路径参数:
响应:
更新指定 Webhook 端点的配置。只需提交要修改的字段,未提交的字段保持原值。
路径参数:
请求参数:
响应:
示例:
删除指定 Webhook 端点,停止接收新事件通知。已开始发送的通知仍可能送达。
路径参数:
响应:
启用指定 Webhook 端点,恢复接收新事件。禁用期间产生的事件不会补发。
路径参数:
请求参数: 无
响应:
禁用指定 Webhook 端点,停止接收新事件通知,保留端点配置。已开始发送的通知仍可能送达。
路径参数:
请求参数: 无
响应:
列出已产生的 Webhook 事件记录,用于审计和排查。
返回事件记录,不包含投递结果。需要确认通知是否收到或处理成功时,请查看接收服务的日志。
请求参数:
响应:
获取单个 Webhook 事件记录的详细信息。
路径参数:
响应:
请求参数无效等 API 错误使用以下格式。例如,事件名含空格时返回
错误字段说明:
根据 HTTP 状态码和错误分类处理,
收到
使用 Standard Webhooks 官方库验证通知,无需自行实现签名算法。将创建端点时保存的完整
每次投递包含以下 HTTP 请求头:
请求头名称不区分大小写,直接将接收到的请求头传给验签库。
安装依赖:
将以下代码保存为
安装依赖:
将以下代码保存为
以上示例展示接收和验签流程,请在注释位置补充去重和业务处理。实际接入时,通过公网 HTTPS 443 地址将请求转发到接收服务;本地监听地址不能直接注册为端点。
注册端点
先准备一个接收通知的 URL:它需要能从公网访问,使用 HTTPS 的 443 端口,并接受 POST 请求。
调用管理 API 时,在 $QODER_ACCESS_TOKEN 中设置个人访问令牌(PAT)或服务账号令牌(SAT)。创建端点后返回的 signing_secret 用于通知验签。
根据资源所在区域设置 QODER_BASE_URL:
| 区域 | Base URL |
|---|---|
| Global | https://api.qoder.com/api/v1/cloud |
| CN | https://api.qoder.com.cn/api/v1/cloud |
url 替换为你的接收地址。本例订阅 session.status_idled,在 Agent 等待工具处理或新的用户输入时接收通知。
id,并将其用于后续示例的 $QODER_WEBHOOK_ENDPOINT_ID。signing_secret 只在创建时返回一次,请安全保存。
处理通知前,先按验证签名配置接收端。使用原始请求体验签,并检查时间戳。
处理事件
验签通过后,再解析请求体并处理事件:
- 用顶层
id去重。已经处理过的通知,直接返回2xx。 - 根据
data.type处理事件,需要详情时按资源查询表调用 GET 接口;删除事件可以直接用于更新本地记录。 - 接收端返回 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 | string | 通知的唯一 ID,以 whe_ 开头;重试保持不变,与 Webhook-Id 请求头一致 |
created_at | string | 事件发生时间,RFC 3339 UTC 格式;重试保持不变 |
type | string | 固定值 "event" |
data | object | 事件类型和资源标识 |
data.id | string | 事件对应的资源 ID,查询方式见下表。Thread 事件使用 Session ID,Vault Credential 事件使用 Credential ID |
data.type | string | 事件类型字符串,如 "session.status_idled"、"agent.updated" |
data.session_thread_id | string | (仅 Thread 事件)所属的 Session Thread ID |
data.vault_id | string | (仅 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 |
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.created | Session 已创建。 |
session.updated | Session 的属性已更新,例如标题、metadata 或配置。 |
session.archived | Session 已归档。 |
session.deleted | Session 已永久删除。 |
session.status_run_started | Session 开始或恢复运行,包括工具操作处理完成或重试后恢复。 |
session.status_idled | Agent 进入空闲状态,例如本轮运行结束、因错误停止,或等待工具确认、自定义工具结果。 |
session.status_rescheduled | 发生可重试错误,Session 正在重新调度。 |
session.status_terminated | Session 已归档并终止。 |
session.thread_created | Session 中创建了新的子 Thread。 |
session.thread_idled | Thread 进入空闲状态,例如任务结束、因错误停止,或等待工具处理。主 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.created | Vault 已创建。 |
vault.archived | Vault 已归档,其中的每条凭证也会触发 vault_credential.archived。 |
vault.deleted | Vault 已删除,其中的每条凭证也会触发 vault_credential.deleted。 |
vault_credential.created | 凭证已创建。 |
vault_credential.archived | 凭证已归档,可能是单独归档,也可能随所属 Vault 一同归档。 |
vault_credential.deleted | 凭证已删除,可能是单独删除,也可能随所属 Vault 一同删除。 |
vault_credential.refresh_failed | mcp_oauth 凭证无法刷新,例如授权失效、刷新配置错误,或 OAuth 服务拒绝刷新请求。 |
4xx(408、429 除外)会触发此事件,即使响应中没有标准 OAuth 错误码。超时、限流、网络错误和 5xx 不触发此事件,可稍后重试。
Agent 事件
这些事件描述 Agent 资源的变化。Agent 的消息和工具调用通过 Session 事件流读取。
| 事件类型 | 触发条件 |
|---|---|
agent.created | Agent 已创建。 |
agent.updated | Agent 的新版本已发布。 |
agent.archived | Agent 已归档,无法用于创建新的 Session。 |
agent.deleted | Agent 已永久删除。 |
Deployment 事件
| 事件类型 | 触发条件 |
|---|---|
deployment.created | Deployment 已创建。 |
deployment.updated | Deployment 的属性已更新,例如调度表达式。 |
deployment.paused | Deployment 已暂停,可能由用户暂停,也可能在首次遇到不可恢复的定时启动错误后自动暂停,例如引用的 Environment 已归档或服务账号绑定失效。临时网络故障、限流等可恢复错误不会因此自动暂停。 |
deployment.unpaused | Deployment 已恢复调度。 |
deployment.archived | Deployment 已归档。 |
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 可查看错误详情。 |
deployment_run.started,随后发送 deployment_run.succeeded 或 deployment_run.failed,两条通知的 data.id 相同。手动运行创建 Session 成功时发送 started 和 succeeded;创建失败时只发送 failed。通知可能乱序或重复,请分别处理并按通知 ID 去重。
Session 创建后的执行超时、错误或完成,通过 Session 事件和对应的状态查询接口跟踪,不会再改变本次 Run 的创建结果通知。
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 已删除。 |
API 参考
本节介绍端点管理和事件记录查询接口。路径中的 {id} 为端点 ID;/webhook_events/{id} 使用事件记录 ID。
Base URL、访问令牌和端点 ID 的设置见注册端点。下列接口均需要 Authorization: Bearer $QODER_ACCESS_TOKEN。
POST /webhook_endpoints
创建一个新的 Webhook 端点。
请求参数:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
url | string | 是 | 接收通知的 URL,必须使用公网可访问的 HTTPS 地址,端口为 443 |
description | string | 否 | 端点描述,便于管理识别 |
metadata | object | 否 | 自定义字符串键值对,默认 {};最多 16 项,键最多 64 个字符,值最多 512 个字符 |
events | string[] | 是 | 订阅的事件类型列表,至少包含一项;使用事件类型中的完整名称,不支持通配符 |
201 Created
注意: signing_secret 仅在创建时返回一次,请安全保存。用它验签的方法见验证签名。
状态码:
| 状态码 | 说明 |
|---|---|
| 201 | 创建成功 |
| 400 | 请求参数无效(如 URL 格式无效、events 为空、事件名称格式不合法或 metadata 不符合约束) |
| 401 | 未授权,Token 无效或过期 |
| 409 | 超过每用户可创建的端点数量上限,error.type 为 invalid_request_error |
GET /webhook_endpoints
获取当前账户下的 Webhook 端点列表。
请求参数:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
limit | integer | 否 | 返回条数,默认 50,最大 100 |
200 OK
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | 端点唯一标识 |
url | string | 接收事件的 URL |
description | string | 端点描述 |
metadata | object | 自定义字符串键值对 |
events | string[] | 订阅的事件类型列表 |
active | boolean | 是否启用。被自动禁用时为 false |
disabled_reason | string | 自动禁用的原因,存在时返回 |
consecutive_fail | integer | 连续投递失败次数 |
last_success_at | string | 最近一次成功投递时间(RFC 3339),无成功记录时不返回 |
last_failure_at | string | 最近一次投递失败时间(RFC 3339),无失败记录时不返回 |
created_at | string | 创建时间(RFC 3339) |
updated_at | string | 最近更新时间(RFC 3339) |
GET /webhook_endpoints/{id}
获取指定 Webhook 端点的详细信息。
路径参数:
| 参数 | 类型 | 说明 |
|---|---|---|
id | string | Webhook 端点 ID |
200 OK
返回单个端点对象,结构与列表接口中的元素一致。
状态码:
| 状态码 | 说明 |
|---|---|
| 200 | 成功 |
| 404 | 端点不存在 |
PUT /webhook_endpoints/{id}
更新指定 Webhook 端点的配置。只需提交要修改的字段,未提交的字段保持原值。
路径参数:
| 参数 | 类型 | 说明 |
|---|---|---|
id | string | Webhook 端点 ID |
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
url | string | 否 | 更新接收地址,必须使用公网可访问的 HTTPS 地址,端口为 443 |
description | string | 否 | 更新端点描述 |
metadata | object | 否 | 按键合并,值为 null 时删除该键;{} 不清空原值。合并后遵守创建接口的数量和长度限制 |
events | string[] | 否 | 替换订阅的事件类型列表,至少包含一项 |
200 OK
返回更新后的完整端点对象。
状态码:
| 状态码 | 说明 |
|---|---|
| 200 | 更新成功 |
| 400 | 请求参数无效 |
| 404 | 端点不存在 |
DELETE /webhook_endpoints/{id}
删除指定 Webhook 端点,停止接收新事件通知。已开始发送的通知仍可能送达。
路径参数:
| 参数 | 类型 | 说明 |
|---|---|---|
id | string | Webhook 端点 ID |
204 No Content
状态码:
| 状态码 | 说明 |
|---|---|
| 204 | 删除成功 |
| 404 | 端点不存在 |
POST /webhook_endpoints/{id}/enable
启用指定 Webhook 端点,恢复接收新事件。禁用期间产生的事件不会补发。
路径参数:
| 参数 | 类型 | 说明 |
|---|---|---|
id | string | Webhook 端点 ID |
200 OK
返回启用后的端点对象(active: true)。
状态码:
| 状态码 | 说明 |
|---|---|
| 200 | 启用成功 |
| 404 | 端点不存在 |
POST /webhook_endpoints/{id}/disable
禁用指定 Webhook 端点,停止接收新事件通知,保留端点配置。已开始发送的通知仍可能送达。
路径参数:
| 参数 | 类型 | 说明 |
|---|---|---|
id | string | Webhook 端点 ID |
200 OK
返回禁用后的端点对象(active: false)。
状态码:
| 状态码 | 说明 |
|---|---|
| 200 | 禁用成功 |
| 404 | 端点不存在 |
GET /webhook_events
列出已产生的 Webhook 事件记录,用于审计和排查。
返回事件记录,不包含投递结果。需要确认通知是否收到或处理成功时,请查看接收服务的日志。
请求参数:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
limit | integer | 否 | 返回条数,默认 50,最大 100 |
200 OK
响应的 data 字段包含按产生时间倒序排列的事件记录;无记录时为 null。每条记录的主要字段如下:
| 字段 | 类型 | 说明 |
|---|---|---|
id | integer | 事件记录 ID,用于查询单条记录 |
event_type | string | 事件类型,如 session.status_idled |
payload | object | 通知的 JSON 内容;其中 payload.id 是 whe_ 开头的通知 ID |
created_at | string | 记录创建时间(RFC 3339) |
GET /webhook_events/{id}
获取单个 Webhook 事件记录的详细信息。
路径参数:
| 参数 | 类型 | 说明 |
|---|---|---|
id | integer | 事件记录 ID,取自列表响应的 id;通知中的 whe_ ID 不用于此接口 |
200 OK
返回单条事件记录,字段与列表接口中的记录一致。
状态码:
| 状态码 | 说明 |
|---|---|
| 200 | 成功 |
| 400 | id 不是有效的 64 位有符号整数 |
| 404 | 事件不存在 |
错误响应格式
请求参数无效等 API 错误使用以下格式。例如,事件名含空格时返回 400:
| 字段 | 类型 | 说明 |
|---|---|---|
error.message | string | 人类可读的错误描述 |
error.type | string | 错误分类(如 invalid_request_error、not_found_error) |
request_id | string | 请求追踪 ID,存在时返回;排查问题时提供给支持团队 |
type | string | 固定值 "error" |
message 用于说明原因,不应作为固定标识。排查步骤见出错怎么办。
认证失败时,响应体可能由网关返回,不使用上述 error.type 结构。例如,缺少 Authorization 时返回 HTTP 401:
401 时,先检查访问令牌,再根据实际响应读取 code 或 error.type。
验证签名
使用 Standard Webhooks 官方库验证通知,无需自行实现签名算法。将创建端点时保存的完整 signing_secret 设置为环境变量 QODER_WEBHOOK_SIGNING_SECRET,保留 whsec_ 前缀。
verify() 验证签名和时间戳,通过后返回解析后的事件;签名无效或时间戳与当前时间相差超过 5 分钟时会抛出异常。必须传入原始请求体,不能先解析 JSON 再重新序列化。
请求头
每次投递包含以下 HTTP 请求头:
| Header | 值 / 说明 |
|---|---|
Content-Type | application/json; charset=utf-8 |
User-Agent | QoderCloudAgents-Webhook/1.0 |
Webhook-Id | 通知 ID,与请求体顶层的 id 相同;重试时不变,用于去重 |
Webhook-Timestamp | 本次签名的 Unix 时间戳(秒),重试时重新生成。业务事件发生时间见 Payload 的 created_at |
Webhook-Signature | 本次投递的签名值 |
Webhook-Event-Type | 事件类型,与 data.type 一致 |
示例:Node.js
安装依赖:
receiver.cjs,运行 node receiver.cjs。此路由应在 express.json() 等 JSON 解析中间件之前注册。
示例:Python
安装依赖:
receiver.py,运行 flask --app receiver run --port 3000。