Filmsquare BantuanPanduan

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.

Diperbarui 4 menit baca.md

Di halaman ini
  1. Berlangganan
  2. Event
  3. Pengiriman
  4. Data tiap event
  5. Memeriksa tanda tangan
  6. Jawaban dan percobaan ulang
  7. Saat langganan dimatikan
  8. Terkait

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_…"}
  • 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.
RuteFungsinya
GET /workspaces/{ws}/webhooksMendaftar langganan (tanpa secret)
POST /workspaces/{ws}/webhooksBerlangganan; 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 #

JenisDikirim saat
generation.succeededTake selesai dirender
generation.failedRender gagal (juga saat Filmsquare mencobanya lagi sendiri)
take.selectedTake dipilih pada sebuah shot atau adegan
asset_version.createdRender 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": ["…"]}}
HeaderNilai
x-fs-signaturesha256= + HMAC-SHA256 heksadesimal dari body mentah, dengan secret Anda sebagai kunci
x-fs-eventJenis event
x-fs-deliveryId event. Event yang sama selalu punya id yang sama

Data tiap event #

JenisField data
generation.succeededgenerationId, takeId, shotId, sceneId, elementId, kind, tier, provider, modelKey, costCredits, assetVersionIds
generation.failedgenerationId, takeId, tier, attempt, error, retryGenerationId (percobaan otomatis berikutnya, atau null)
take.selectedselectionId, takeId, assetVersionId, shotId, sceneId, kind, selectedBy
asset_version.createdassetVersionId, 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 AndaYang dilakukan Filmsquare
2xxSelesai
5xx, 429, timeout, atau error jaringanMencoba lagi setelah sekitar 10 detik, 1 menit, dan 5 menit, sampai 4 percobaan
410Langsung mematikan langganan
4xx lainnyaMenyerah 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:

KolomNilai
consecutive_failuresPercobaan gagal berturut-turut
consecutive_slowHitungan lambat: naik 1 untuk tiap jawaban lebih dari 5 detik, turun 1 untuk tiap jawaban yang lebih cepat
failing_sinceKapan rangkaian kegagalan saat ini dimulai, atau null
disabled_atKapan dimatikan, atau null
disabled_reasonMengapa 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.

Halaman ini sebagai Markdown: /docs/id/api/webhooks.md