接收 Webhook 事件

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

HTTP 请求

事件发生后，Qoder Cloud Agents 会向 Endpoint URL 发送 HTTP POST 请求：

POST /webhooks/qoder HTTP/1.1
Content-Type: application/json; charset=utf-8
User-Agent: QoderCloudAgents-Webhook/1.0
Webhook-ID: whe_01k1jbxexample
Webhook-Event-Type: forward.schedule_run.succeeded
Webhook-Timestamp: 1788253679
Webhook-Signature: v1,BASE64_HMAC_SHA256

Header	说明
`Webhook-ID`	事件 ID。相同事件重试时保持不变，可用作消费幂等键。
`Webhook-Event-Type`	事件类型。
`Webhook-Timestamp`	生成签名时的 Unix 秒时间戳。
`Webhook-Signature`	请求签名，当前格式为 `v1,<base64>`。

接收端返回任意 2xx 表示处理成功。建议先完成验签并将事件写入自己的可靠队列，再快速返回响应。

事件结构

Forward 业务事件使用统一信封：

{
  "type": "event",
  "id": "whe_01k1jbxexample",
  "created_at": "2026-09-01T09:07:59Z",
  "data": {
    "type": "forward.schedule_run.succeeded",
    "id": "srun_01k1jbrexample",
    "schema_version": 1,
    "run_id": "srun_01k1jbrexample",
    "schedule_id": "sched_01k1jbqexample",
    "identity_id": "idn_01k1jbnexample",
    "template_id": "tmpl_01k1jbmexample",
    "status": "completed",
    "trigger_type": "schedule",
    "attempt": 1,
    "push_status": "succeeded",
    "duration_ms": 15432
  }
}

字段	类型	说明
`type`	string	固定为 `event`。
`id`	string	Webhook 事件 ID，与 `Webhook-ID` 相同。
`created_at`	string	事件发生时间，RFC 3339 格式。
`data.type`	string	事件类型，与 `Webhook-Event-Type` 相同。
`data.id`	string	发生事件的资源 ID。
`data.schema_version`	integer	事件数据版本，当前为 `1`。

客户端应忽略暂不识别的新增字段，以便兼容后续扩展。

Schedule 事件

`forward.schedule.created`

Schedule 创建成功时发送：

{
  "type": "event",
  "id": "whe_01k1jbxcreated",
  "created_at": "2026-09-01T09:00:00Z",
  "data": {
    "type": "forward.schedule.created",
    "id": "sched_01k1jbqexample",
    "schema_version": 1,
    "schedule_id": "sched_01k1jbqexample",
    "identity_id": "idn_01k1jbnexample",
    "template_id": "tmpl_01k1jbmexample",
    "status": "active",
    "trigger_policy_type": "cron",
    "next_trigger_at": "2026-09-02T01:00:00Z"
  }
}

trigger_policy_type 和 next_trigger_at 仅在有对应值时返回。

`forward.schedule_run.succeeded`

Schedule Run 成功完成时发送。data.status 为 completed。

`forward.schedule_run.failed`

Schedule Run 执行失败时发送。结构与成功事件相同，data.status 为 failed，并可能包含 error_type：

{
  "type": "event",
  "id": "whe_01k1jbxfailed",
  "created_at": "2026-09-01T09:07:59Z",
  "data": {
    "type": "forward.schedule_run.failed",
    "id": "srun_01k1jbrfailed",
    "schema_version": 1,
    "run_id": "srun_01k1jbrfailed",
    "schedule_id": "sched_01k1jbqexample",
    "identity_id": "idn_01k1jbnexample",
    "template_id": "tmpl_01k1jbmexample",
    "status": "failed",
    "trigger_type": "schedule",
    "attempt": 1,
    "push_status": "failed",
    "duration_ms": 1200,
    "error_type": "runtime_error"
  }
}

Schedule Run 事件的业务结果应以对应的 Schedule Run 查询接口为准；Webhook 用于通知状态变化。

Managed Agents 资源事件

Forward 也支持订阅 Session、Session Thread、Agent、Environment、Memory Store、Vault 和 Vault Credential 事件。完整事件名及触发时机见支持的公开事件。这些事件使用相同的外层信封，但 data 仅携带资源引用，不包含 Schedule 事件的 schema_version、业务状态或结果正文。例如，会话进入空闲状态：

{
  "type": "event",
  "id": "whe_01k1jbxidled",
  "created_at": "2026-09-01T09:07:59Z",
  "data": {
    "type": "session.status_idled",
    "id": "sess_01k1jbsexample"
  }
}

事件类别	`data.id`	额外字段
`session.status_*`、`session.updated`、`session.deleted`	Session ID	无。
`session.thread_*`	所属 Session ID	`session_thread_id`：具体线程 ID。
`agent.*`	Managed Agent ID	无。
`environment.*`	Environment ID	无。
`memory_store.*`	Memory Store ID	无。
`vault.*`	Vault ID	无。
`vault_credential.*`	Vault Credential ID	`vault_id`：所属 Vault ID。

表中的 * 仅用于归类，不是可填写到 events 的前缀通配符。收到通知后，可按资源 ID 查询当前详情；删除事件对应的资源可能已无法查询。session.status_idled 不等同于业务成功，应结合会话输出和状态判断。 webhook.test 不使用上述资源事件结构，测试载荷见发送测试事件。

签名校验

创建 Endpoint 时返回的 signing_secret 用于验证请求签名。签名内容由以下三部分组成：

signed_content = Webhook-ID + "." + Webhook-Timestamp + "." + raw_body

校验时需要使用未经解析、未经重新序列化的原始请求 Body。 Python 示例：

import base64
import hashlib
import hmac
import time


def verify_webhook(
    secret: str,
    webhook_id: str,
    timestamp: str,
    signature_header: str,
    raw_body: bytes,
    tolerance_seconds: int = 300,
) -> bool:
    if not secret.startswith("whsec_"):
        return False

    try:
        ts = int(timestamp)
        key = base64.b64decode(secret[len("whsec_"):], validate=True)
    except (ValueError, TypeError):
        return False

    if abs(int(time.time()) - ts) > tolerance_seconds:
        return False

    signed_content = (
        webhook_id.encode()
        + b"."
        + timestamp.encode()
        + b"."
        + raw_body
    )
    expected = base64.b64encode(
        hmac.new(key, signed_content, hashlib.sha256).digest()
    ).decode()

    signatures = [
        value.removeprefix("v1,")
        for value in signature_header.split()
        if value.startswith("v1,")
    ]
    return any(hmac.compare_digest(expected, value) for value in signatures)

建议同时校验：

Webhook-Timestamp 与当前时间的偏差不超过 5 分钟。
Webhook-Signature 至少包含一个验签成功的 v1 签名。
已处理过的 Webhook-ID 不再重复执行有副作用的业务操作。

重试与幂等

Webhook 使用至少一次投递语义。网络失败、超时或接收端返回非 2xx 时，系统可能重试同一事件。

使用 Webhook-ID 去重，不要使用请求到达时间生成幂等键。
同一个 Webhook-ID 的重复请求应返回成功，且不得重复执行副作用。
处理失败时返回非 2xx；处理成功或已处理过时返回 2xx。

接收 Webhook 事件

HTTP 请求

事件结构

Schedule 事件

`forward.schedule.created`

`forward.schedule_run.succeeded`

`forward.schedule_run.failed`

Managed Agents 资源事件

签名校验

重试与幂等

相关

创建 Webhook Endpoint

发送测试事件

​HTTP 请求

​事件结构

​Schedule 事件

​forward.schedule.created

​forward.schedule_run.succeeded

​forward.schedule_run.failed

​Managed Agents 资源事件

​签名校验

​重试与幂等

​相关

创建 Webhook Endpoint

发送测试事件

HTTP 请求

事件结构

Schedule 事件

`forward.schedule.created`

`forward.schedule_run.succeeded`

`forward.schedule_run.failed`

Managed Agents 资源事件

签名校验

重试与幂等

相关