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ığı.
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_…"}
eventsolay 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 birhttpya dahttpsadresi 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
409vewebhook_limitkoduyla cevaplanır.
| Rota | Ne yapar |
|---|---|
GET /workspaces/{ws}/webhooks | Abonelikleri listeler (secret'siz) |
POST /workspaces/{ws}/webhooks | Abone 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ür | Ne zaman gönderilir |
|---|---|
generation.succeeded | Bir çekimin render'ı bitti |
generation.failed | Bir render başarısız oldu (Filmsquare onu kendiliğinden yeniden denerken de) |
take.selected | Bir planda ya da sahnede bir çekim seçildi |
asset_version.created | Bir 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ık | Değer |
|---|---|
x-fs-signature | sha256= + ham gövdenin secret'ınla anahtarlanmış hex HMAC-SHA256'sı |
x-fs-event | Olay türü |
x-fs-delivery | Olay id'si. Aynı olay her zaman aynı id'ye sahiptir |
Her olayın verisi #
| Tür | data alanları |
|---|---|
generation.succeeded | generationId, takeId, shotId, sceneId, elementId, kind, tier, provider, modelKey, costCredits, assetVersionIds |
generation.failed | generationId, takeId, tier, attempt, error, retryGenerationId (otomatik sonraki deneme, ya da null) |
take.selected | selectionId, takeId, assetVersionId, shotId, sceneId, kind, selectedBy |
asset_version.created | assetVersionId, 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ın | Filmsquare ne yapar |
|---|---|
2xx | Tamam |
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 |
410 | Aboneliği hemen kapatır |
Diğer her 4xx | Bu 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
410ile cevap verdiyse, ya da - URL'in çoğu zaman yavaşsa. 5 saniyeden uzun süren her cevap,
2xxdahil, 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:
| Alan | Değer |
|---|---|
consecutive_failures | Üst üste başarısız denemeler |
consecutive_slow | Yavaş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_at | Ne zaman kapatıldığı ya da null |
disabled_reason | Neden 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.