---
title: "테이크가 준비되면 웹훅을 받으려면 어떻게 하나요?"
description: "프로듀서나 소유자가 API로 URL을 구독해요. 전송은 x-fs-signature로 서명되고, 내 서버가 실패하면 재시도돼요."
url: https://www.filmsquare.ai/help/ko/connect/webhooks/
lang: ko
section: connect
updated: 2026-11-13
---

웹훅은 테이크가 끝나거나, OK컷이 선택되거나, 새 버전이 도착할 때 내 URL로 이벤트를 보내요. 그래서 폴링할 필요가 없어요. 웹훅은 프로듀서나 소유자가 API로 설정해요. 스튜디오에는 웹훅 화면이 없어요.

## 구독하기

`/v1/workspaces/{ws}/webhooks`에 `url`과 원하는 `events`(전체는 `["*"]`)를 담아 `POST`를 보내요. 응답에 `secret`이 한 번만 들어 있어요. 모든 전송을 확인하는 데 필요하니 저장해 두세요. URL은 공개 호스트의 `http` 또는 `https` 주소여야 해요. 키가 필요해요. [API 키는 어떻게 받나요](https://www.filmsquare.ai/help/ko/connect/api-keys/)를 보세요. 요청 방법은 문서의 [구독](https://www.filmsquare.ai/docs/ko/api/webhooks/#subscribe)에 있어요.

## 이벤트

이벤트는 네 가지예요. `generation.succeeded`, `generation.failed`, `take.selected`, `asset_version.created`예요. 개인 스케치북에 있는 테이크의 이벤트는 절대 보내지 않아요. 각 이벤트의 필드는 [이벤트별 데이터](https://www.filmsquare.ai/docs/ko/api/webhooks/#the-data-of-each-event)에 있어요.

## 확인하고 응답하기

모든 전송에는 `x-fs-signature` 헤더가 있어요. `sha256=`에 내 secret을 키로 한 원본 본문의 16진수 HMAC-SHA256이 붙어요. 서명이 맞지 않는 전송은 거부하세요. 코드는 [서명 확인](https://www.filmsquare.ai/docs/ko/api/webhooks/#check-the-signature)에 있어요.

어떤 `2xx` 상태로든 빠르게 응답하세요. `5xx`, `429`, 시간 초과, 네트워크 오류는 백오프와 함께 최대 8번까지 재시도돼요. 그 밖의 `4xx`는 전송을 끝내요. 전송이 두 번 이상 올 수 있으므로 `x-fs-delivery`로 이미 처리한 이벤트를 건너뛰세요.

> [!NOTE]
> 웹훅은 Filmsquare 밖으로 데이터를 보내기 때문에 내 Claude는 웹훅에 접근할 수 없어요.
