Webhooks

Webhooksを使用すると、生成プロセスが完了した際に非同期通知を受け取ることができます。更新を確認するために/api/v1/status/{id}エンドポイントを手動でポーリングする代わりに、ジョブが完了するとすぐにシステムが最終ペイロードを直接サーバーにプッシュします。

Webhooksの使用方法

当社のAPIでWebhooksを使用するには、/runリクエストにwebhook_urlパラメーターを追加するだけです。

生成プロセスが完了した際（成功した場合、またはランタイムエラーが発生した場合）、当社のディスパッチャーは、完全なステータスペイロードを含むPOSTリクエストを指定されたWebhook URLに送信します。

例: /runエンドポイントでのWebhooksの使用

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ペイロード

Webhook URLに配信されるペイロードは、/v1/status/{id}エンドポイントによって返されるペイロードと同一です。ジョブの最終状態が含まれています。

成功ペイロード

プロセスが正常に完了すると、Webhook URLはstatusが"success"に設定され、結果がoutput配列に含まれるPOSTリクエストを受け取ります。

{
  "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"
}

Webhookのセキュリティ

受信するWebhooksが実際にFit It Onから発信されたものであり、悪意のある第三者によって偽造されたものではないことを確認するために、検証メカニズムを実装する必要があります。

Webhooksを保護する最も簡単な方法は、/v1/runリクエストで提供するwebhook_urlにシークレットトークンを追加することです。

例: シークレットトークンの使用

生成プロセスを開始する際、URLクエリパラメーターに非常にランダムな文字列を追加します。

// Make sure to URL-encode the webhook URL if it contains query parameters!
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ヘッダーを調べることができます。

ベストプラクティス

1. 冪等性の実装: ネットワークの状態や当社のリトライメカニズムにより、サーバーが同じWebhookを複数回受信する可能性があります。idフィールドを使用して、そのイベントをすでに処理したかどうかを確認する必要があります。
2. 迅速な応答: 画像のダウンロードやデータベースの更新を行う前に、常に200 OKステータスをすぐに返してください。
3. 常にWebhooksを検証する: Webhooksが当社のサービスから送信されていることを確認し、悪意のあるアクターによるペイロードの偽装を防ぐために、検証メカニズム（上記のシークレットURLトークンのようなもの）の実装を検討してください。