Skip to main content
Webhook 在异步任务完成、失败或超时时通知你的应用。可在 Dashboard → API → Webhooks、管理 API 或 TokenLab MCP 的 full 模式配置;三者使用同一工作区的端点和投递记录。

用哪个 Key

在 Dashboard → API → Management Tokens 创建管理令牌,选择与提交模型任务的 API Key 相同的工作区。令牌只能访问所属工作区,不能跨工作区读取或修改 Webhook。sk-… 和 whsec_… 不能代替 mt-…。Dashboard 配置使用已登录的工作区管理员身份。 管理令牌与签名密钥只保存在后端,不放入前端代码、提示词、代码仓库或 URL。Management Token 还可调用其他工作区管理接口,并不是只拥有 Webhook 权限的专用令牌。

创建与管理

成功返回 201,包含端点 id 和仅显示一次的 secret(whsec_…)。立即安全保存;查询、列表、更新响应不包含签名密钥。每个工作区最多 10 个端点。URL 必须是公网 HTTPS,不能包含账号密码、查询参数或 fragment;不跟随重定向。 PATCH {"is_active":false} 暂停,PATCH {"is_active":true} 恢复并重置连续失败计数。轮换只返回一次新密钥,接收端应立即更新;正在发送的请求可能仍使用旧密钥,切换时可短暂同时接受新旧两把密钥。轮换不可撤销。

事件与载荷

订阅的是之后产生的异步任务终态事件,不补发历史事件,也不针对同步结果发送通知。同一工作区内符合事件类型的任务都会触发通知,用 data.taskId 关联创建响应的任务 ID。通知字段使用 camelCase,管理 API 响应使用 snake_case。
字段依任务而定,可能缺省。使用原工作区的 sk-… 查询 GET /v1/tasks/{id},获取权威结果和计费状态。失败事件的 retryable 描述生成失败是否可重试,不表示应持续轮询终态任务,也不授权自动创建新的付费任务。

先验签,再处理

请求头包含 X-Webhook-ID、X-Webhook-Timestamp(Unix 秒)和 X-Webhook-Signature(sha256=<hex>)。使用完整 whsec_… 作为密钥,对时间戳原字符串、一个英文句点和原始请求体字节计算 HMAC-SHA256。不能先解析 JSON 再序列化验签。
验签后检查请求体 id 与 X-Webhook-ID 相同,把事件 ID 与处理任务原子保存,尽快返回 2xx,耗时业务由自己的队列处理。通知可能重复、乱序,应按接收端点和事件 ID 去重。五分钟时间窗口限制过旧请求,事件 ID 去重阻止窗口内重复处理。

重试、记录与恢复

每轮最多尝试 3 次,间隔为 1 秒、4 秒;单次 HTTP 超时 10 秒,每次重算时间戳和签名。网络失败、429、5xx 可重试;其他 4xx、重定向、非法网络地址停止本轮投递。暂时失败可能触发后续事件重试,继续使用同一投递 ID。连续 10 轮失败会自动暂停端点。 通过测试接口和投递记录查看 outcome、http_status、累计 attempts 和 delivered_at。测试接口返回 200 只表示尝试已记录,必须检查 outcome == "delivered" 才算接收成功。修复接收服务、恢复端点,再发送测试。历史记录只保存投递元数据,不保存完整载荷,暂不提供手工重放历史事件;接收服务暂停或不可用期间,应保留任务 ID 并用任务查询补偿核对。

MCP 配置

Webhook 工具位于 full 模式。管理令牌与模型 Key 分开配置;仅使用目录和 Webhook 管理时不需要模型 Key。
工具包括 list_webhooks、create_webhook、get_webhook、update_webhook、delete_webhook、rotate_webhook_secret、test_webhook、list_webhook_deliveries。凭据不作为工具参数填写,只向可信 MCP 客户端授予管理访问权。

轮询兜底

Webhook 不取消查询能力,也不新增轮询限额。轮询时使用创建响应里的 poll_url,处理中逐步增加间隔,终态后停止。遇到 401、403、404 或 error.retryable == false 停止;503 async_task_owner_unavailable 属于临时故障,可退避重试。不存在或过期的任务返回 404 async_task_not_found,重复查询不能恢复或创建任务。 Seedance 兼容 API 的 callback_url 是独立的单任务回调,在创建请求中配置;它不使用这里的工作区事件载荷或 HMAC 请求头。