跳到主要内容

Task 回调 (Webhooks)

你可以通过 Task API 发布任务,并让自己的服务接收经过签名的状态回调 (Webhooks),再查询任务结果。 本页介绍杭州 staging 的接入方式;生产环境尚未开放这套 callback API。

服务身份与公钥​

Staging 的服务身份 (Service Identity) 固定为 https://task.staging.openhex.tech,签名算法为 Ed25519。你使用自己的 Task API key 调用 API;OpenHex Task 使用服务私钥签署回调。公钥不会授予 API 访问权限。

配置地址或值
Task APIhttps://task.staging.openhex.tech/api
MCP endpointhttps://task.staging.openhex.tech/mcp
Service identityhttps://task.staging.openhex.tech
Signing key IDopenhex-task-staging-20261011-1c1df131
Public key (PEM)下载公钥
Public keys (JWKS)下载 JWKS
Identity metadata查看身份记录

私钥仅保存在服务端。验签时预先信任本页的 service identity 和公钥,不使用回调请求自行提供的公钥地址。Staging key 只用于 staging。

1. 准备接收 endpoint​

Callback endpoint 需要使用 HTTPS、443 端口,并解析到公网 IP;服务不跟随 redirect。私网地址、带登录凭据或 fragment 的 URL 不接受注册。

注册时,Task 服务向该 endpoint 发送签名的 callback.verify:

{
"version": 1,
"subscription_id": "callback:verification-id",
"message_id": "verification-message-id",
"type": "callback.verify",
"data": { "challenge": "random-challenge" }
}

你验签通过后,返回 HTTP 2xx 和 JSON {"challenge":"random-challenge"},原样回传这次收到的值。Ownership challenge 验证失败时不会保存 callback。

2. 注册 callback​

在 Task webapp 的 Settings 中创建 API key,选择允许的 agents 和所需 permissions。Callback 注册需要 task:publish;查询结果需要 task:read,关闭或继续任务需要 task:manage。

export TASK_API=https://task.staging.openhex.tech/api
# TASK_API_KEY 保存你自己的 Task API key;不要放到浏览器或源码里。
curl --fail-with-body "$TASK_API/callbacks" \
-H "Authorization: Bearer $TASK_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"url":"https://your-service.example/task-events","types":["task.blocked","task.completed","task.closed"]}'

成功响应包含 id、url、types、verified_at 和 revoked_at。省略 types 时订阅全部五种 task events。同一 API key 使用相同 URL/types 重试注册会返回原 callback。

每个 API key 只能使用、列出和撤销自己注册的 callbacks;owner login 可以查看和撤销账号下全部 callbacks。用另一个 API key 访问原 task 仍然不被允许。

3. 创建 task 时绑定 callback​

curl --fail-with-body "$TASK_API/tasks" \
-H "Authorization: Bearer $TASK_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"agentId":"YOUR_AGENT_ID","prompt":"生成一段小红书文案,并提交完整 task_result。","idempotencyKey":"copywriting-001","callbackId":"YOUR_CALLBACK_ID"}'

你也可以传 callbackUrl,它必须已经用同一 credential 完成注册。callbackId 和 callbackUrl 二选一;推荐保留 callback ID,用稳定的 idempotencyKey 重试发布。改变 callback 后不能复用原 task 的 idempotency key。当前每个 task 支持一个 external callback。

MCP 提供 register_callback、list_callbacks、revoke_callback;publish_task、publish_tasks 和 task-augmented execute_task 接受相同的 callback 字段。

4. 接收状态并获取结果​

Task 推送简短的 notification envelope,不推送 prompt、完整结果或文件内容:

{
"version": 1,
"subscription_id": "task:business-task-id",
"message_id": "stable-event-id",
"type": "task.completed",
"data": { "execution_id": "execution-handle-id", "result_version": 1, "outcome": "succeeded" }
}
Event含义
task.blockedExecutor 需要检查或补充输入
task.result_updated数据库中的结果 revision 已更新
task.completed当前 execution 完成,business task 仍可继续
task.execution.cancelled当前 execution handle 已取消
task.closedPublisher 关闭 business task,binding 自动关闭

从 subscription_id 取出 task ID,再用发布时的同一 API key 请求 GET /api/tasks/TASK_ID,读取权威的 task_result。Execution handle 的冻结结果可通过 GET /api/executions/EXECUTION_ID 查询。多个任务可使用同一个 callback;每项任务有自己的 binding 和 event sequence。

验签与可靠接收​

请求使用 HTTP Message Signatures (RFC 9421) 和 Content-Digest (RFC 9530)。固定签名 profile 覆盖 POST method、完整目标 URL、body digest、content type、service identity,以及 created、expires、keyid 和 alg。

你可以使用 Node.js 验签函数:

const notification = verifyTaskWebhook({
url: configuredCallbackUrl, // 注册时的完整 URL;不要从不可信代理头拼接
headers: request.headers,
body: rawBody, // 验签前保留原始 bytes
serviceId: 'https://task.staging.openhex.tech',
jwks: trustedPublicKeys,
});

签名有效期为五分钟。验签成功后,还要检查你的已注册 task/subscription 与 allowed types;签名仅证明发送方身份。

推送采用 at-least-once delivery。你应在自己的数据库中以 service identity + message_id 去重,可靠保存事件后尽快返回 2xx,再异步处理。重试保留相同 envelope/message ID,但重新签名。HTTP 非 2xx、timeout 或连接失败会退避重试;同一 binding 内保持事件顺序,不同 bindings 可独立投递。

撤销 callback​

GET /api/callbacks 列出 callbacks;DELETE /api/callbacks/CALLBACK_ID 撤销 endpoint 并丢弃未投递通知。已经接收的 HTTP 消息无法撤回。API key 被撤销、过期或失去目标 agent 的 publish 权限时,该任务 binding 的待投递通知停止投递。

task.completed 不关闭 binding。task.closed 的最终通知与关闭状态原子保存,最终通知仍会重试;reopen 不恢复旧 binding。当前不支持修改既有 task 的 callback 或为 reopened task 重新订阅。

下一步​