> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fetchhive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 回调投递与 Webhook 触发

> 通过 API 调用或 Webhook 触发启动工作流部署，将结果发送到回调 URL，并验证签名回调投递

# 回调投递与 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 触发工作流？ <a href="#trigger-workflow-webhook" id="trigger-workflow-webhook" />

在工作流侧边栏中打开 **More** 并点击 **Get Code**，或从工作流部署页面打开 **Code Snippet**。

选择你要触发的 **Deployment** 和 **Variant**，然后打开 **Webhook trigger** 选项卡。

复制 Webhook URL，并在 `X-Fetch-Hive-Webhook-Secret` 中携带部署密钥发送 `POST` 请求：

```bash theme={null}
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` 字段是必填的：

```json theme={null}
{
  "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 启用回调投递？ <a href="#generate-callback-request" id="generate-callback-request" />

在工作流侧边栏中打开 **More** 并点击 **Get Code**，或从工作流部署页面打开 **Code Snippet**。

选择你要调用的 **Deployment** 和 **Variant**。

打开 **Callback delivery**。

cURL 代码段将更新为包含：

```json theme={null}
{
  "async": {
    "enabled": true,
    "callback_url": "https://example.com/callback"
  }
}
```

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

{/* Add screenshot: callback delivery cURL snippet in the workflow get code modal */}

## 如何验证回调签名？ <a href="#verify-webhook-signatures" id="verify-webhook-signatures" />

在代码段对话框中打开 **Callback delivery**，或打开 **Webhook trigger** 选项卡。

复制代码段下方显示的 **Signing secret**，或从工作流部署详情页面查看同一密钥。

当你的服务器接收到回调事件时，使用 HMAC SHA256 和该签名密钥验证 `X-Fetch-Hive-Signature` 请求头。

将任何签名验证失败的回调事件视为不可信。

如果工作流是通过 Webhook 触发启动的，此签名密钥与触发系统在 `X-Fetch-Hive-Webhook-Secret` 中发送的值相同。入站触发检查是 bearer 风格的密钥检查；出站回调检查是 HMAC 签名验证。

## 启用回调投递后我会收到什么响应？ <a href="#callback-response" id="callback-response" />

启用回调投递后，公共路由会立即返回，而不会等待工作流输出。

对于直接投递，公共 API 只会在同步 timeout 窗口内等待。如果工作流超过
该窗口，Fetch Hive 会请求取消并返回 `504`，响应中包含 `request_id` 和
`run_status: "failed"`。长时间运行的工作流或包含 Human in the Loop 步骤的
工作流应使用回调投递。

API invoke 路由可以返回 `running` 状态：

```json theme={null}
{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "run_status": "running",
  "webhook_secret": "YOUR_WEBHOOK_SECRET"
}
```

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

```json theme={null}
{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "run_status": "queued",
  "webhook_secret": "YOUR_WEBHOOK_SECRET"
}
```

使用返回的 `request_id` 进行你自己的请求跟踪，并依靠回调投递获取最终结果。

工作流 Webhook 触发也会快速返回：

```json theme={null}
{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "run_status": "running"
}
```

## 回调投递有哪些验证规则？ <a href="#callback-validation" id="callback-validation" />

如果 `async.enabled` 为 `true`，则 `callback_url` 是必填的。

Webhook 触发始终需要 `async.callback_url`。

Fetch Hive 还会验证 `callback_url` 是一个有效的 URL。

包含 Human in the Loop 步骤的工作流始终需要回调投递，即便是 API invoke 请求也是如此。它们无法同步完成，因为 Fetch Hive 会暂停工作流，直到所选工作区成员做出响应。

例如，以下错误已被明确确认：

```json theme={null}
{
  "error": "callback_url is required when async is enabled"
}
```

```json theme={null}
{
  "error": "callback_url must be a valid URL"
}
```

## Fetch Hive 会发出哪些回调事件？ <a href="#webhook-events" id="webhook-events" />

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

```json theme={null}
{
  "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` 负载示例：

```json theme={null}
{
  "event_type": "workflow.cancelled",
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "data": {
    "error": "Workflow cancelled: Activity canceled",
    "reason": "cancelled"
  }
}
```

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

## 启动后我在哪里查看回调投递？ <a href="#inspect-callback-activity" id="inspect-callback-activity" />

工作流启动后请使用 [日志](./logs)。

对于使用了回调投递的运行，工作流运行详情视图可以显示 **Callback** 标记、**Callback delivery** 部分、输出和 **Webhook Logs**。**Webhook Logs** 指的是回调投递尝试，而非运行来源。

如果回调投递失败，日志视图还可以显示每次投递尝试的重试历史和响应详情。

## 注意事项

Webhook 触发、带有回调投递的 API invoke 请求和签名回调事件是工作流生命周期中相互独立的部分。Webhook 触发启动一次运行。回调投递控制 Fetch Hive 是否立即返回并存储一个回调 URL。签名回调事件是最终结果稍后到达该回调 URL 的方式。

如果你不需要回调投递，请保持禁用状态并使用 [使用 API 运行](./run-with-api) 中记录的常规直接响应。

另请参阅：[使用 API 运行](./run-with-api)、[日志](./logs) 和 [错误处理](./error-handling)