6.0 API6.2 Webhook
Webhook
Berlangganan URL ke event Filmsquare, empat jenis event dan payload-nya, cara pengiriman ditandatangani dengan x-fs-signature, dan cara kerja percobaan ulang.
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 #
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_…"}
eventsadalah daftar jenis event, atau["*"]untuk semuanya.urlharus berupa alamathttpatauhttpsdi 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
409dan kodewebhook_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:
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.
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.