---
title: "Webhook"
description: "Filmsquareのイベントにurlを登録します。4つのイベントの種類とペイロード、x-fs-signatureによる署名、再試行の仕組みを説明します。"
url: https://www.filmsquare.ai/docs/ja/api/webhooks/
lang: ja
section: api
updated: 2026-11-17
---

# Webhook

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

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

## 登録する

```bash
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"]}'
```

```json
{"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_…"}
```

> [!NOTE]
> `secret`が返されるのは、ここだけです。保管してください。すべての配信の確認に必要です。

- `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`です。

```http
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全体です。比較は、定数時間で行ってください。

```js
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`を返します。先にエンドポイントを直してください。

## 関連ページ

- [APIの概要とキー](https://www.filmsquare.ai/docs/ja/api/overview/)
- [OpenAPIリファレンス](https://www.filmsquare.ai/docs/ja/api/openapi/)
