网络钩子

当您的图像或视频生成过程完成时，接收异步的实时 HTTP 通知。

网络钩子（Webhooks）允许您在生成过程完成时接收异步通知。您无需手动轮询 /api/v1/status/{id} 端点来检查更新，我们的系统会在作业完成后立即将最终负载直接推送到您的服务器。

如何使用网络钩子

要将网络钩子与我们的 API 结合使用，只需将 webhook_url 参数附加到您的 /run 请求中：

POSThttps://fititon.app/api/v1/run?webhook_url=https://your-server.com/webhook

当生成过程完成时（无论是成功还是遇到运行时错误），我们的调度器将向您指定的 webhook URL 发送一个 POST 请求，其中包含完整的状态负载。

安全要求 出于安全目的（SSRF 保护），您的 webhook_url 必须使用 HTTPS (https://)。内部或私有 IP 地址（例如 localhost、127.0.0.1 或 192.168.x.x）被严格阻止。如果您在本地开发，请使用安全的隧道服务，如 Ngrok 或 Cloudflare Tunnels。

示例：将网络钩子与 `/run` 端点结合使用

fetch("https://fititon.app/api/v1/run?webhook_url=https://your-server.com/webhook", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY",
  },
  body: JSON.stringify({
    model_name: "product-to-model",
    inputs: {
      image: "http://example.com/path/to/garment.jpg",
      // ... other inputs
    }
  }),
});

网络钩子负载

发送到您的 webhook URL 的负载与 /v1/status/{id} 端点返回的负载相同。它包含作业的最终状态。

成功负载

当过程成功完成时，您的 webhook URL 将收到一个 POST 请求，其中 status 设置为 "success"，结果位于 output 数组中：

{
  "id": "123a87r9-4129-4bb3-be18-9c9fb5bd7fc1",
  "status": "success",
  "output": [
    "https://cdn.fititon.app/users/123/results/output_0.png"
  ],
  "error": null,
  "created_at": "2026-07-24T17:30:00.000Z",
  "updated_at": "2026-07-24T17:31:15.000Z"
}

错误负载

如果过程因运行时错误（例如，无法识别的服装、严格的审核过滤器）而失败，您的 webhook URL 将收到确切的错误字符串。

{
  "id": "123a87r9-4129-4bb3-be18-9c9fb5bd7fc1",
  "status": "failed",
  "output": null,
  "error": {
    "name": "InputValidationError",
    "message": "The provided garment image could not be processed due to poor lighting."
  },
  "created_at": "2026-07-24T17:30:00.000Z",
  "updated_at": "2026-07-24T17:30:12.000Z"
}

网络钩子安全

为确保您收到的网络钩子确实源自 Fit It On，而非恶意第三方伪造，您应实施验证机制。

保护您的网络钩子最简单的方法是在 /v1/run 请求中提供的 webhook_url 后附加一个秘密令牌。

示例：使用秘密令牌

当您启动生成过程时，将一个高度随机的字符串附加到您的 URL 查询参数中：

// 如果 webhook URL 包含查询参数，请务必进行 URL 编码！
const myWebhookUrl = encodeURIComponent("https://your-server.com/webhook?token=a8f9c2d1e5b47...");

fetch(`https://fititon.app/api/v1/run?webhook_url=${myWebhookUrl}`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY",
  },
  // ...
  body: JSON.stringify({
    model_name: "product-to-model",
    inputs: {
      image: "http://example.com/path/to/garment.jpg",
    }
  }),
});

当您的服务器收到 webhook POST 请求时，只需在处理 JSON 负载之前验证 token 查询参数是否与您的秘密字符串匹配即可。

保证交付与重试

我们的系统实施了企业级重试机制，以确保您绝不会错过任何 webhook 交付，即使您的服务器暂时停机。

超时： 我们的调度器强制执行严格的 15 秒超时。您的服务器必须在 15 秒内以 2xx HTTP 状态码确认 webhook。如果您需要执行繁重处理（例如下载图像），您应该首先响应 webhook，然后异步处理数据。
失败： 如果您的服务器返回非 2xx 状态码（例如 500 Internal Server Error），或未能在 15 秒内响应，我们则认为交付失败。
指数退避： 系统将使用指数退避（例如，在 5 分钟、15 分钟、45 分钟等时间后重试）尝试最多 5 次重试。

如果您需要知道当前是第几次重试尝试访问您的服务器，您可以检查每个 webhook 请求中包含的 x-fititon-retry-count 头部。

最佳实践

实现幂等性： 由于网络条件和我们的重试机制，您的服务器技术上可能会多次接收到相同的 webhook。您应该使用 id 字段来检查您是否已处理过该事件。
快速响应： 在下载图像或更新数据库之前，始终立即返回 200 OK 状态。
始终验证网络钩子： 考虑实施验证机制（如上述秘密 URL 令牌），以确保网络钩子来自我们的服务，并防止恶意行为者伪造负载。