Filmsquare YardımDokümanlar

6.0 API6.2 Webhook'lar

Webhook'lar

Bir URL'yi Filmsquare olaylarına abone et; dört olay türü ve yükleri, teslimlerin x-fs-signature ile nasıl imzalandığı ve yeniden denemelerin nasıl çalıştığı.

Güncellendi 4 dk okuma.md

Bu sayfada
  1. Abone ol
  2. Olaylar
  3. Teslim
  4. Her olayın verisi
  5. İmzayı kontrol et
  6. Cevap ve yeniden denemeler
  7. Bir abonelik kapatıldığında
  8. İlgili

Bir webhook, bir çalışma alanında bir şey olduğunda URL'ne bir olay gönderir: bir çekim bitti ya da başarısız oldu, bir çekim seçildi, yeni bir versiyon geldi. Yoklama yerine onu kullan.

Webhook'ları bir yapımcı ya da sahip API üzerinden yönetir. Stüdyoda bunlar için bir ekran yok ve Claude'un onlara ulaşamaz (Filmsquare'in dışına veri gönderirler).

Abone ol #

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 olay türlerinin bir listesidir, ya da hepsi için ["*"].
  • url, herkese açık bir host'ta, içinde kullanıcı adı ya da şifre olmayan bir http ya da https adresi olmalı.
  • Bir çalışma alanında en fazla 10 etkin abonelik olabilir. 11.si ya da 10'u aşacak şekilde bir tanesini açmak 409 ve webhook_limit koduyla cevaplanır.
RotaNe yapar
GET /workspaces/{ws}/webhooksAbonelikleri listeler (secret'siz)
POST /workspaces/{ws}/webhooksAbone eder; secret'ı bir kez döner
PATCH /workspaces/{ws}/webhooks/{id}url, events ya da active değiştirir
DELETE /workspaces/{ws}/webhooks/{id}Teslimleri durdurur (abonelik devre dışı bırakılır, silinmez)

Dördü de yapımcı rolü ya da üstünü gerektirir.

Olaylar #

TürNe zaman gönderilir
generation.succeededBir çekimin render'ı bitti
generation.failedBir render başarısız oldu (Filmsquare onu kendiliğinden yeniden denerken de)
take.selectedBir planda ya da sahnede bir çekim seçildi
asset_version.createdBir render yeni bir varlık versiyonu üretti

Bir kişinin özel eskiz defterindeki (Create) çekimlerle ilgili olaylar hiçbir zaman gönderilmez.

Teslim #

Her teslim, URL'ne olayı JSON gövdesi olarak taşıyan bir POST'tur:

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": ["…"]}}
BaşlıkDeğer
x-fs-signaturesha256= + ham gövdenin secret'ınla anahtarlanmış hex HMAC-SHA256'sı
x-fs-eventOlay türü
x-fs-deliveryOlay id'si. Aynı olay her zaman aynı id'ye sahiptir

Her olayın verisi #

Türdata alanları
generation.succeededgenerationId, takeId, shotId, sceneId, elementId, kind, tier, provider, modelKey, costCredits, assetVersionIds
generation.failedgenerationId, takeId, tier, attempt, error, retryGenerationId (otomatik sonraki deneme, ya da null)
take.selectedselectionId, takeId, assetVersionId, shotId, sceneId, kind, selectedBy
asset_version.createdassetVersionId, takeId, generationId, mime

Bir varlık versiyonunun dosyasını GET /workspaces/{ws}/asset-versions/{id}/url ile al (imzalı bir indirme URL'si).

İmzayı kontrol et #

HMAC'i ham istek gövdesi üzerinde, aynen alındığı gibi, ayrıştırmadan önce hesapla. Anahtar, whsec_ dahil secret'ın tamamı. Sabit zamanda karşılaştır.

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

İmzası uyuşmayan bir teslimi reddet.

Cevap ve yeniden denemeler #

Herhangi bir 2xx durumuyla, hızlıca cevap ver. Yavaş işi cevap verdikten sonra yap. Filmsquare cevabını en fazla 10 saniye bekler; daha yavaş bir cevap başarısız bir deneme sayılır.

CevabınFilmsquare ne yapar
2xxTamam
5xx, 429, bir zaman aşımı ya da bir ağ hatasıYaklaşık 10 saniye, 1 dakika ve 5 dakika sonra yeniden dener, en fazla 4 deneme
410Aboneliği hemen kapatır
Diğer her 4xxBu teslimden vazgeçer

Bir teslim birden fazla kez gelebilir ve olaylar sırasız gelebilir. Zaten ele aldığın olayları atlamak için x-fs-delivery'yi, sıralamak için createdAt'i kullan.

Bir çalışma alanı için 500'den fazla teslim bekliyorsa, o alanın yeni olayları kuyruğa alınmaz.

Bir abonelik kapatıldığında #

2xx almayan her deneme başarısız sayılır: bir zaman aşımı, bir ağ hatası ya da başka herhangi bir durum. Bir 2xx sayacı 0'a döndürür. Filmsquare aboneliği şu durumlarda kapatır (active false olur):

  • üst üste 5 veya daha fazla deneme başarısız olduysa ve bunların ilki en az 10 dakika önceyse, ya da
  • URL'in 410 ile cevap verdiyse, ya da
  • URL'in çoğu zaman yavaşsa. 5 saniyeden uzun süren her cevap, 2xx dahil, bir yavaşlık sayacına 1 ekler; daha hızlı her cevap 1 düşer (asla 0'ın altına inmez). Sayaç 20'ye ulaşınca abonelik kapatılır. Bir zaman aşımı ya da ağ hatası yalnızca başarısız deneme sayılır, asla yavaş sayılmaz.

Bir dağıtım gibi kısa bir kesinti aboneliği kapatmaz. Kapatılmış bir abonelik için hâlâ bekleyen teslimler gönderilmez ve çalışma alanının sahipleri gelen kutularında bir bildirim alır, abonelik başına günde en fazla bir kez. Abonelik nedenini gösterir:

AlanDeğer
consecutive_failuresÜst üste başarısız denemeler
consecutive_slowYavaşlık sayacı: 5 saniyeden yavaş her cevapta 1 artar, daha hızlı her cevapta 1 azalır
failing_sinceŞu anki başarısızlık serisinin ne zaman başladığı ya da null
disabled_atNe zaman kapatıldığı ya da null
disabled_reasonNeden kapatıldığı ya da null

Aboneliği yeniden açmak için webhook'u "active": true ile güncelle. Bu, consecutive_failures ve consecutive_slow değerlerini 0'a döndürür ve nedeni siler. Kendini kapatan bir abonelik 24 saat içinde 3 kez yeniden açılabilir. Sonrasında güncelleme 409 ve webhook_rearm_limit koduyla cevap verir: önce endpoint'ini düzelt.

Bu sayfa Markdown olarak: /docs/tr/api/webhooks.md