6.0 API6.2 웹훅
웹훅
URL을 Filmsquare 이벤트에 구독하고, 네 가지 이벤트 유형과 페이로드, x-fs-signature로 서명하는 방법, 재시도 방식을 알려 드려요.
웹훅은 워크스페이스에서 무슨 일이 생기면 내 URL로 이벤트를 보내요. 테이크 렌더가 끝났거나 실패했을 때, 테이크가 OK컷으로 골라졌을 때, 새 버전이 들어왔을 때예요. 폴링하는 대신 써요.
웹훅은 프로듀서나 소유자가 API로 관리해요. 스튜디오에는 웹훅 화면이 없고, 내 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주소여야 하고, 계정 이름이나 비밀번호는 들어갈 수 없어요.- 워크스페이스 하나에 활성 구독은 최대 10개까지 둘 수 있어요. 11번째 구독이나 10개를 넘겨 다시 켜는 요청에는
409와 코드webhook_limit가 돌아와요.
| 경로 | 하는 일 |
|---|---|
GET /workspaces/{ws}/webhooks | 구독 목록(secret 없이) |
POST /workspaces/{ws}/webhooks | 구독. secret을 한 번 돌려줘요 |
PATCH /workspaces/{ws}/webhooks/{id} | url, events, active 변경 |
DELETE /workspaces/{ws}/webhooks/{id} | 전송 중단(구독은 삭제되지 않고 비활성화돼요) |
넷 모두 프로듀서 역할 이상이 필요해요.
이벤트 #
| 유형 | 보내는 때 |
|---|---|
generation.succeeded | 테이크 렌더가 끝났을 때 |
generation.failed | 렌더가 실패했을 때(Filmsquare가 알아서 다시 시도할 때도 포함) |
take.selected | 컷이나 씬에서 테이크가 OK컷으로 골라졌을 때 |
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 hex |
x-fs-event | 이벤트 유형 |
x-fs-delivery | 이벤트 id. 같은 이벤트는 항상 같은 id예요 |
이벤트별 데이터 #
| 유형 | 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으로 맞추세요.
워크스페이스 하나에 전송이 500건보다 많이 대기 중이면, 그 워크스페이스의 새 이벤트는 대기열에 넣지 않아요.
구독이 꺼질 때 #
2xx를 받지 못한 시도는 모두 실패로 세요. 타임아웃, 네트워크 오류, 그 밖의 모든 상태가 해당돼요. 2xx로 답하면 횟수가 0으로 돌아가요. 다음 중 하나에 해당하면 Filmsquare가 구독을 꺼요(active가 false가 돼요).
- 연속 5번 이상 시도가 실패했고, 그중 첫 실패가 10분 이상 전일 때
- URL이
410으로 답했을 때 - URL이 절반 넘게 느리게 답할 때. 5초보다 오래 걸린 응답은
2xx라도 지연 횟수에 1을 더하고, 더 빠른 응답은 1을 빼요(0 아래로는 내려가지 않아요). 20이 되면 구독이 꺼져요. 타임아웃이나 네트워크 오류는 실패한 시도로만 세고, 느린 응답으로는 세지 않아요.
배포 같은 짧은 장애로는 꺼지지 않아요. 꺼진 구독에 대기 중이던 전송은 보내지 않고, 워크스페이스 소유자의 알림함에 알림이 가요. 알림은 구독 하나당 하루에 한 번까지예요. 구독에 이유가 표시돼요.
| 필드 | 값 |
|---|---|
consecutive_failures | 연속으로 실패한 시도 수 |
consecutive_slow | 지연 횟수: 5초보다 느린 응답마다 1 늘고, 더 빠른 응답마다 1 줄어요 |
failing_since | 지금의 연속 실패가 시작된 시각, 또는 null |
disabled_at | 꺼진 시각, 또는 null |
disabled_reason | 꺼진 이유, 또는 null |
다시 켜려면 웹훅을 "active": true로 업데이트하세요. consecutive_failures와 consecutive_slow가 0으로 돌아가고 이유도 지워져요. 스스로 꺼진 구독은 24시간에 3번까지 다시 켤 수 있어요. 그 뒤에는 업데이트가 409와 코드 webhook_rearm_limit로 답해요. 엔드포인트부터 고치세요.