---
title: "Webhook"
description: "Berlangganan URL ke event Filmsquare, empat jenis event dan payload-nya, cara pengiriman ditandatangani dengan x-fs-signature, dan cara kerja percobaan ulang."
url: https://www.filmsquare.ai/docs/id/api/webhooks/
lang: id
section: api
updated: 2026-11-17
---

# Webhook

Webhook mengirim event ke URL Anda saat sesuatu terjadi di ruang kerja: take selesai atau gagal, take
dipilih, versi baru masuk. Pakai ini sebagai ganti polling.

Webhook dikelola lewat API oleh produser atau pemilik. Tidak ada layarnya di studio, dan
Claude Anda tidak bisa menjangkaunya (webhook mengirim data keluar dari Filmsquare).

## Berlangganan

```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` hanya dikembalikan di sini. Simpan: Anda membutuhkannya untuk memeriksa setiap pengiriman.

- `events` adalah daftar jenis event, atau `["*"]` untuk semuanya.
- `url` harus berupa alamat `http` atau `https` di host publik, tanpa nama pengguna atau kata sandi di dalamnya.
- Satu ruang kerja bisa punya paling banyak 10 langganan aktif. Langganan ke-11, atau mengaktifkan satu lagi melewati 10, dijawab dengan `409` dan kode `webhook_limit`.

| Rute | Fungsinya |
| --- | --- |
| `GET /workspaces/{ws}/webhooks` | Mendaftar langganan (tanpa secret) |
| `POST /workspaces/{ws}/webhooks` | Berlangganan; mengembalikan secret sekali |
| `PATCH /workspaces/{ws}/webhooks/{id}` | Mengubah `url`, `events`, atau `active` |
| `DELETE /workspaces/{ws}/webhooks/{id}` | Menghentikan pengiriman (langganan dinonaktifkan, tidak dihapus) |

Keempatnya butuh peran produser atau lebih tinggi.

## Event

| Jenis | Dikirim saat |
| --- | --- |
| `generation.succeeded` | Take selesai dirender |
| `generation.failed` | Render gagal (juga saat Filmsquare mencobanya lagi sendiri) |
| `take.selected` | Take dipilih pada sebuah shot atau adegan |
| `asset_version.created` | Render menghasilkan versi aset baru |

Event tentang take di buku sketsa pribadi seseorang (Create) tidak pernah dikirim.

## Pengiriman

Setiap pengiriman adalah `POST` ke URL Anda dengan event sebagai body JSON-nya:

```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": ["…"]}}
```

| Header | Nilai |
| --- | --- |
| `x-fs-signature` | `sha256=` + HMAC-SHA256 heksadesimal dari body mentah, dengan secret Anda sebagai kunci |
| `x-fs-event` | Jenis event |
| `x-fs-delivery` | Id event. Event yang sama selalu punya id yang sama |

### Data tiap event

| Jenis | Field `data` |
| --- | --- |
| `generation.succeeded` | `generationId`, `takeId`, `shotId`, `sceneId`, `elementId`, `kind`, `tier`, `provider`, `modelKey`, `costCredits`, `assetVersionIds` |
| `generation.failed` | `generationId`, `takeId`, `tier`, `attempt`, `error`, `retryGenerationId` (percobaan otomatis berikutnya, atau `null`) |
| `take.selected` | `selectionId`, `takeId`, `assetVersionId`, `shotId`, `sceneId`, `kind`, `selectedBy` |
| `asset_version.created` | `assetVersionId`, `takeId`, `generationId`, `mime` |

Ambil file sebuah versi aset dengan `GET /workspaces/{ws}/asset-versions/{id}/url` (URL unduh bertanda tangan).

## Memeriksa tanda tangan

Hitung HMAC atas body permintaan mentah, persis seperti diterima, sebelum Anda mem-parse-nya. Kuncinya adalah seluruh secret,
termasuk `whsec_`. Bandingkan dalam waktu konstan.

```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));
}
```

Tolak pengiriman yang tanda tangannya tidak cocok.

## Jawaban dan percobaan ulang

Jawab dengan status `2xx` apa pun, dengan cepat. Kerjakan yang lambat setelah Anda menjawab. Filmsquare menunggu jawaban Anda paling lama 10 detik; jawaban yang lebih lambat dihitung sebagai percobaan gagal.

| Jawaban Anda | Yang dilakukan Filmsquare |
| --- | --- |
| `2xx` | Selesai |
| `5xx`, `429`, timeout, atau error jaringan | Mencoba lagi setelah sekitar 10 detik, 1 menit, dan 5 menit, sampai 4 percobaan |
| `410` | Langsung mematikan langganan |
| `4xx` lainnya | Menyerah pada pengiriman ini |

Pengiriman bisa tiba lebih dari sekali, dan event bisa tiba tidak berurutan. Pakai `x-fs-delivery` untuk melewati event yang
sudah ditangani, dan `createdAt` untuk mengurutkannya.

Jika lebih dari 500 pengiriman menunggu untuk satu ruang kerja, event baru untuk ruang kerja itu tidak dimasukkan ke antrean.

### Saat langganan dimatikan

Setiap percobaan yang tidak mendapat `2xx` dihitung gagal: timeout, error jaringan, atau status lainnya. Jawaban `2xx` mengembalikan hitungan ke 0. Filmsquare mematikan langganan (`active` menjadi `false`) jika:

- 5 percobaan atau lebih berturut-turut gagal, dan yang pertama setidaknya 10 menit lalu, atau
- URL Anda menjawab `410`, atau
- URL Anda lebih sering lambat daripada tidak. Setiap jawaban yang memakan waktu lebih dari 5 detik, termasuk `2xx`, menambah 1 pada hitungan lambat, dan setiap jawaban yang lebih cepat menguranginya 1 (tidak pernah di bawah 0). Pada 20, langganan dimatikan. Timeout atau error jaringan hanya dihitung sebagai percobaan gagal, tidak pernah sebagai lambat.

Gangguan singkat, seperti saat deploy, tidak mematikannya. Pengiriman yang masih menunggu untuk langganan yang dimatikan tidak dikirim, dan para pemilik ruang kerja mendapat notifikasi di Inbox mereka, paling banyak sekali sehari per langganan. Langganan menunjukkan alasannya:

| Kolom | Nilai |
| --- | --- |
| `consecutive_failures` | Percobaan gagal berturut-turut |
| `consecutive_slow` | Hitungan lambat: naik 1 untuk tiap jawaban lebih dari 5 detik, turun 1 untuk tiap jawaban yang lebih cepat |
| `failing_since` | Kapan rangkaian kegagalan saat ini dimulai, atau `null` |
| `disabled_at` | Kapan dimatikan, atau `null` |
| `disabled_reason` | Mengapa dimatikan, atau `null` |

Untuk menyalakannya lagi, perbarui webhook dengan `"active": true`. Ini mengembalikan `consecutive_failures` dan `consecutive_slow` ke 0 dan menghapus alasannya. Langganan yang mematikan dirinya sendiri bisa dinyalakan lagi 3 kali dalam 24 jam. Setelah itu pembaruan menjawab `409` dengan kode `webhook_rearm_limit`: perbaiki endpoint Anda dulu.

## Terkait

- [Ikhtisar API dan kunci](https://www.filmsquare.ai/docs/id/api/overview/)
- [Referensi OpenAPI](https://www.filmsquare.ai/docs/id/api/openapi/)
