回调投递与 Webhook 触发

Fetch Hive 将运行的启动方式与结果返回方式分离：

API invoke 使用工作区 API 密钥通过 POST /v1/workflow/invoke 启动运行。
Webhook trigger 使用部署 Webhook 密钥通过 POST /v1/workflow/webhooks/... 启动已部署的变体。
Callback delivery 立即返回，并随后向 async.callback_url 发送签名的完成事件。

为了 API 兼容性，请求字段仍命名为 async，但产品行为是回调投递。

概述

工作流部署助手为所选部署变体公开了 API 调用和 Webhook 触发功能。Webhook 触发使用部署 Webhook 密钥，不需要工作区 API 密钥。 API invoke 请求可以选择直接投递或回调投递。当你包含 async.callback_url 时，Fetch Hive 会立即返回，并随后向该 URL 投递签名的回调事件。 Webhook 触发始终使用回调投递。它们需要 async.callback_url，会快速返回，并仅通过签名的回调事件投递最终结果。两个方向都使用相同的部署密钥。调用方通过在 X-Fetch-Hive-Webhook-Secret 中发送该密钥来证明其有权启动已部署的工作流。你的回调接收方通过使用 HMAC SHA256 和同一密钥验证 X-Fetch-Hive-Signature 来证明后续事件来自 Fetch Hive。

如何通过 Webhook 触发工作流？

在工作流侧边栏中打开 More 并点击 Get Code，或从工作流部署页面打开 Code Snippet。选择你要触发的 Deployment 和 Variant，然后打开 Webhook trigger 选项卡。复制 Webhook URL，并在 X-Fetch-Hive-Webhook-Secret 中携带部署密钥发送 POST 请求：

curl 'https://api.fetchhive.com/v1/workflow/webhooks/YOUR_WORKFLOW_ENDPOINT_ID/variants/YOUR_VARIANT_ID' \
  -H 'X-Fetch-Hive-Webhook-Secret: YOUR_WEBHOOK_SECRET' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "inputs": {
      "topic": "State of enterprise AI in 2026"
    },
    "async": {
      "callback_url": "https://example.com/callback"
    }
  }'

如果你的 Webhook 提供商无法发送自定义请求头，你可以传递 ?secret=YOUR_WEBHOOK_SECRET 作为替代方案。在提供商支持时，优先使用请求头。请使用助手中显示的部署 Webhook 密钥。这是 Fetch Hive 用于为该部署签名回调投递事件的同一密钥。当请求体中包含 inputs 对象时，Fetch Hive 将该对象用作工作流的启动输入。如果请求体是不包含 inputs 的 JSON 对象，Fetch Hive 会将整个对象视为工作流输入。你还可以在 inputs 旁包含可选的 user 和 metadata 字段。async.callback_url 字段是必填的：

{
  "inputs": {
    "topic": "State of enterprise AI in 2026"
  },
  "user": {
    "id": "user_123",
    "email": "person@example.com"
  },
  "metadata": {
    "source_system": "zapier"
  },
  "async": {
    "callback_url": "https://example.com/callback"
  }
}

metadata 是调用方定义的用户元数据，用于审计和日志过滤。它必须是一个扁平对象，其值为字符串、数字、布尔值或 null；嵌套对象和数组会在运行启动之前返回验证错误。要发送元数据，请使用上面所示的包装请求体形式，将 metadata 与 inputs 并列。如果你省略 inputs，则整个 JSON 对象会被视为工作流输入，因此 metadata 不会被提取为日志过滤元数据。通过 Webhook 触发的运行在工作流日志中显示为 Source: Webhook，并显示 Delivery: Callback 及回调投递日志。

如何为 API invoke 启用回调投递？

在工作流侧边栏中打开 More 并点击 Get Code，或从工作流部署页面打开 Code Snippet。选择你要调用的 Deployment 和 Variant。打开 Callback delivery。 cURL 代码段将更新为包含：

{
  "async": {
    "enabled": true,
    "callback_url": "https://example.com/callback"
  }
}

在运行请求之前，将示例回调 URL 替换为你的真实 Webhook 端点。

如何验证回调签名？

在代码段对话框中打开 Callback delivery，或打开 Webhook trigger 选项卡。复制代码段下方显示的 Signing secret，或从工作流部署详情页面查看同一密钥。当你的服务器接收到回调事件时，使用 HMAC SHA256 和该签名密钥验证 X-Fetch-Hive-Signature 请求头。将任何签名验证失败的回调事件视为不可信。如果工作流是通过 Webhook 触发启动的，此签名密钥与触发系统在 X-Fetch-Hive-Webhook-Secret 中发送的值相同。入站触发检查是 bearer 风格的密钥检查；出站回调检查是 HMAC 签名验证。

启用回调投递后我会收到什么响应？

启用回调投递后，公共路由会立即返回，而不会等待工作流输出。 API invoke 路由可以返回 running 状态：

{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "run_status": "running",
  "webhook_secret": "YOUR_WEBHOOK_SECRET"
}

在高并发情况下，它也可能返回 queued 状态：

{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "run_status": "queued",
  "webhook_secret": "YOUR_WEBHOOK_SECRET"
}

使用返回的 request_id 进行你自己的请求跟踪，并依靠回调投递获取最终结果。工作流 Webhook 触发也会快速返回：

{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "run_status": "running"
}

回调投递有哪些验证规则？

如果 async.enabled 为 true，则 callback_url 是必填的。 Webhook 触发始终需要 async.callback_url。 Fetch Hive 还会验证 callback_url 是一个有效的 URL。包含 Human in the Loop 步骤的工作流始终需要回调投递，即便是 API invoke 请求也是如此。它们无法同步完成，因为 Fetch Hive 会暂停工作流，直到所选工作区成员做出响应。例如，以下错误已被明确确认：

{
  "error": "callback_url is required when async is enabled"
}

{
  "error": "callback_url must be a valid URL"
}

Fetch Hive 会发出哪些回调事件？

每个回调投递都有相同的信封：

{
  "event_type": "<event_type>",
  "request_id": "req_...",
  "data": { "...": "..." }
}

event_type 字段告诉你工作流到达了哪个终止状态：

workflow.completed - 工作流成功完成。data.output 包含最终输出值。
workflow.failed - 工作流在执行期间出错。data.error 包含错误消息。
workflow.cancelled - 工作流在完成之前被取消，可能是由 Fetch Hive 仪表板中的用户取消，或直接通过编排器取消。data.error 包含取消原因，data.reason 始终为字符串 "cancelled"，因此你可以无需解析消息即可进行分支处理。

对于图像生成工作流，workflow.completed 包含一个结构化输出对象：

data.output.settings（使用的模型和设置）
data.output.assets（生成并上传的资产）

workflow.cancelled 负载示例：

{
  "event_type": "workflow.cancelled",
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "data": {
    "error": "Workflow cancelled: Activity canceled",
    "reason": "cancelled"
  }
}

请在你这一端将 workflow.cancelled 视为终止状态。对于该 request_id，不会再投递任何回调事件。该工作流运行的部分进度（包括取消之前完成的任何补全）仍可通过运行详情视图和日志端点查看。

启动后我在哪里查看回调投递？

工作流启动后请使用日志。对于使用了回调投递的运行，工作流运行详情视图可以显示 Callback 标记、Callback delivery 部分、输出和 Webhook Logs。Webhook Logs 指的是回调投递尝试，而非运行来源。如果回调投递失败，日志视图还可以显示每次投递尝试的重试历史和响应详情。

注意事项

Webhook 触发、带有回调投递的 API invoke 请求和签名回调事件是工作流生命周期中相互独立的部分。Webhook 触发启动一次运行。回调投递控制 Fetch Hive 是否立即返回并存储一个回调 URL。签名回调事件是最终结果稍后到达该回调 URL 的方式。如果你不需要回调投递，请保持禁用状态并使用使用 API 运行中记录的常规直接响应。另请参阅：使用 API 运行、日志和错误处理

​回调投递与 Webhook 触发

​概述

​如何通过 Webhook 触发工作流？

​如何为 API invoke 启用回调投递？

​如何验证回调签名？

​启用回调投递后我会收到什么响应？

​回调投递有哪些验证规则？

​Fetch Hive 会发出哪些回调事件？

​启动后我在哪里查看回调投递？

​注意事项