Filmsquare ヘルプドキュメント

6.0 API6.2 Webhook

Webhook

Filmsquareのイベントにurlを登録します。4つのイベントの種類とペイロード、x-fs-signatureによる署名、再試行の仕組みを説明します。

更新日 1分で読めます.md

このページの内容
  1. 登録する
  2. イベント
  3. 配信の内容
  4. 各イベントのdata
  5. 署名を確認する
  6. 応答と再試行
  7. 登録が停止されるとき
  8. 関連ページ

webhookは、ワークスペースで何かが起きたときに、イベントを指定のURLに送ります。テイクが完成した、失敗した、採用された、新しいバージョンが入った、といった場合です。ポーリングの代わりに使います。

webhookは、プロデューサーまたはオーナーが、APIから管理します。Studioに専用の画面はなく、お手持ちのClaudeも触れません(Filmsquareの外にデータを送るためです)。

登録する #

curl -s -X POST "$FS/workspaces/$WS/webhooks" \
  -H "Authorization: Bearer $FS_KEY" -H "content-type: application/json" \
  -d '{"url": "https://example.com/filmsquare/hook", "events": ["generation.succeeded", "take.selected"]}'
{"id": "…", "workspace_id": "…", "url": "https://example.com/filmsquare/hook",
 "events": ["generation.succeeded", "take.selected"], "active": true,
 "created_by": "…", "created_at": "2026-10-26T10:12:03.000Z",
 "secret": "whsec_…"}
  • eventsは、イベントの種類のリストです。すべてなら["*"]です。
  • urlは、公開ホストのhttpまたはhttpsのアドレスで、ユーザー名やパスワードを含んではいけません。
  • 1つのワークスペースで有効にできる登録は、最大10件です。11件目の登録や、10件を超えて有効に戻す操作には、409とコードwebhook_limitが返ります。
ルート内容
GET /workspaces/{ws}/webhooks登録を一覧する(secretなし)
POST /workspaces/{ws}/webhooks登録する。secretは1回だけ返る
PATCH /workspaces/{ws}/webhooks/{id}url、events、activeを変更する
DELETE /workspaces/{ws}/webhooks/{id}配信を止める(登録は削除ではなく無効化される)

4つとも、プロデューサー以上の役割が必要です。

イベント #

種類送られるタイミング
generation.succeededテイクのレンダリングが完了した
generation.failedレンダリングが失敗した(Filmsquareが自動で再試行するときも)
take.selectedカットまたはシーンで、テイクが採用された
asset_version.createdレンダリングで、新しいファイルのバージョンができた

個人のスケッチブック(Create)のテイクに関するイベントは、送られません。

配信の内容 #

各配信は、イベントをJSONのボディにした、指定のURLへのPOSTです。

POST /filmsquare/hook HTTP/1.1
content-type: application/json
x-fs-signature: sha256=5d1c…
x-fs-event: generation.succeeded
x-fs-delivery: generation.succeeded:9b2e…

{"id": "generation.succeeded:9b2e…", "type": "generation.succeeded",
 "workspaceId": "…", "createdAt": "2026-10-26T10:14:51.220Z",
 "data": {"generationId": "9b2e…", "takeId": "…", "shotId": "…", "sceneId": null, "elementId": null,
          "kind": "video", "tier": "draft", "provider": "byteplus", "modelKey": "…",
          "costCredits": 22.7, "assetVersionIds": ["…"]}}
ヘッダー値
x-fs-signaturesha256=に、secretをキーにした、生のボディのHMAC-SHA256(16進数)を続けたもの
x-fs-eventイベントの種類
x-fs-deliveryイベントのid。同じイベントは、常に同じid

各イベントのdata #

種類dataのフィールド
generation.succeededgenerationId, takeId, shotId, sceneId, elementId, kind, tier, provider, modelKey, costCredits, assetVersionIds
generation.failedgenerationId, takeId, tier, attempt, error, retryGenerationId(自動の次の試行。なければnull)
take.selectedselectionId, takeId, assetVersionId, shotId, sceneId, kind, selectedBy
asset_version.createdassetVersionId, takeId, generationId, mime

ファイルのバージョンのファイルは、GET /workspaces/{ws}/asset-versions/{id}/url(署名付きのダウンロードURL)で取得します。

署名を確認する #

HMACは、受け取ったままの生のリクエストボディに対して、パースする前に計算します。キーは、whsec_を含む、secret全体です。比較は、定数時間で行ってください。

import { createHmac, timingSafeEqual } from "node:crypto";

export function isFromFilmsquare(secret, rawBody, header) {
  if (!header) return false;
  const want = "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex");
  return want.length === header.length && timingSafeEqual(Buffer.from(want), Buffer.from(header));
}

署名が一致しない配信は、拒否してください。

応答と再試行 #

任意の2xxステータスで、すばやく応答してください。時間のかかる処理は、応答したあとに行います。Filmsquareが応答を待つのは最長10秒で、それより遅い応答は失敗した試行として数えます。

受信側の応答Filmsquareの動作
2xx完了
5xx、429、タイムアウト、ネットワークエラー約10秒後、1分後、5分後に再試行する。最大4回
410登録をただちに停止する
それ以外の4xxこの配信をあきらめる

配信は、複数回届くことがあり、イベントの順番が前後することもあります。x-fs-deliveryで、処理済みのイベントを飛ばし、createdAtで順番を決めてください。

1つのワークスペースで配信待ちが500件を超えると、そのワークスペースの新しいイベントはキューに入りません。

登録が停止されるとき #

2xxが返らなかった試行はすべて失敗として数えます。タイムアウト、ネットワークエラー、それ以外のステータスが対象です。2xxで応答すると、カウントは0に戻ります。次のいずれかになると、Filmsquareは登録を停止します(activeがfalseになります)。

  • 連続5回以上の試行が失敗し、そのうち最初の失敗が10分以上前のとき
  • URLが410で応答したとき
  • URLの応答が、半分以上の割合で遅いとき。5秒より長くかかった応答は(2xxも含めて)遅延カウントに1を足し、それより速い応答は1を引きます(0より下にはなりません)。カウントが20になると、登録は停止されます。タイムアウトやネットワークエラーは失敗した試行としてだけ数え、遅い応答には数えません。

デプロイなどの短い停止では停止されません。停止した登録の配信待ちは送られず、ワークスペースのオーナーのInboxに通知が届きます。通知は、1つの登録につき1日に1回までです。停止の理由は登録に表示されます。

フィールド値
consecutive_failures連続で失敗した試行の数
consecutive_slow遅延カウント。5秒より遅い応答ごとに1増え、それより速い応答ごとに1減ります
failing_sinceいまの失敗の連続が始まった時刻、またはnull
disabled_at停止された時刻、またはnull
disabled_reason停止された理由、またはnull

再び有効にするには、"active": trueでwebhookを更新します。consecutive_failuresとconsecutive_slowが0に戻り、理由も消えます。自動で停止した登録を再び有効にできるのは、24時間に3回までです。それを超えると、更新は409とコードwebhook_rearm_limitを返します。先にエンドポイントを直してください。

このページのMarkdown: /docs/ja/api/webhooks.md