6.0 API6.2 Webhook
Webhook
Filmsquareのイベントにurlを登録します。4つのイベントの種類とペイロード、x-fs-signatureによる署名、再試行の仕組みを説明します。
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-signature | sha256=に、secretをキーにした、生のボディのHMAC-SHA256(16進数)を続けたもの |
x-fs-event | イベントの種類 |
x-fs-delivery | イベントのid。同じイベントは、常に同じid |
各イベントのdata #
| 種類 | dataのフィールド |
|---|---|
generation.succeeded | generationId, takeId, shotId, sceneId, elementId, kind, tier, provider, modelKey, costCredits, assetVersionIds |
generation.failed | generationId, takeId, tier, attempt, error, retryGenerationId(自動の次の試行。なければnull) |
take.selected | selectionId, takeId, assetVersionId, shotId, sceneId, kind, selectedBy |
asset_version.created | assetVersionId, 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を返します。先にエンドポイントを直してください。