6.0 API6.2 Webhooks
Webhooks
Abonner une URL aux événements Filmsquare, les quatre types d'événements et leurs charges utiles, comment les livraisons sont signées avec x-fs-signature, et comment fonctionnent les nouvelles tentatives.
Un webhook envoie un événement à votre URL quand quelque chose se passe dans un espace de travail : une prise s'est terminée ou a échoué, une prise a été retenue, une nouvelle version est arrivée. Utilisez-le plutôt que d'interroger en boucle.
Les webhooks se gèrent par l'API, par un producteur ou un propriétaire. Il n'y a pas d'écran pour eux dans le studio, et votre Claude ne peut pas les atteindre (ils envoient des données hors de Filmsquare).
S'abonner #
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_…"}
eventsest une liste de types d'événements, ou["*"]pour tous.urldoit être une adressehttpouhttpssur un hôte public, sans nom d'utilisateur ni mot de passe dedans.- Un espace de travail peut avoir au plus 10 abonnements actifs. Le 11e, ou l'activation d'un abonnement au-delà de 10, répond
409avec le codewebhook_limit.
| Route | Fait |
|---|---|
GET /workspaces/{ws}/webhooks | Liste les abonnements (sans secrets) |
POST /workspaces/{ws}/webhooks | S'abonner ; renvoie le secret une seule fois |
PATCH /workspaces/{ws}/webhooks/{id} | Modifie url, events ou active |
DELETE /workspaces/{ws}/webhooks/{id} | Arrête les livraisons (l'abonnement est désactivé, pas supprimé) |
Les quatre demandent le rôle producteur ou plus haut.
Événements #
| Type | Envoyé quand |
|---|---|
generation.succeeded | Le rendu d'une prise est terminé |
generation.failed | Un rendu a échoué (aussi quand Filmsquare le relance de lui-même) |
take.selected | Une prise a été retenue sur un plan ou une séquence |
asset_version.created | Un rendu a produit une nouvelle version de ressource |
Les événements sur les prises du carnet de croquis privé d'une personne (Create) ne sont jamais envoyés.
La livraison #
Chaque livraison est un POST vers votre URL avec l'événement comme corps JSON :
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": ["…"]}}
| En-tête | Valeur |
|---|---|
x-fs-signature | sha256= + le HMAC-SHA256 hexadécimal du corps brut, avec votre secret comme clé |
x-fs-event | Le type d'événement |
x-fs-delivery | L'id de l'événement. Le même événement a toujours le même id |
Les données de chaque événement #
| Type | Champs de data |
|---|---|
generation.succeeded | generationId, takeId, shotId, sceneId, elementId, kind, tier, provider, modelKey, costCredits, assetVersionIds |
generation.failed | generationId, takeId, tier, attempt, error, retryGenerationId (la tentative suivante automatique, ou null) |
take.selected | selectionId, takeId, assetVersionId, shotId, sceneId, kind, selectedBy |
asset_version.created | assetVersionId, takeId, generationId, mime |
Récupérez le fichier d'une version de ressource avec GET /workspaces/{ws}/asset-versions/{id}/url (une URL de
téléchargement signée).
Vérifier la signature #
Calculez le HMAC sur le corps brut de la requête, exactement tel que reçu, avant de l'analyser. La clé est le secret
entier, whsec_ compris. Comparez en temps constant.
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));
}
Rejetez une livraison dont la signature ne correspond pas.
Répondre et nouvelles tentatives #
Répondez avec n'importe quel statut 2xx, rapidement. Faites le travail lent après avoir répondu. Filmsquare attend votre réponse 10 secondes au plus ; une réponse plus lente compte comme un essai échoué.
| Votre réponse | Ce que fait Filmsquare |
|---|---|
2xx | Terminé |
5xx, 429, un délai dépassé ou une erreur réseau | Réessaie après environ 10 secondes, 1 minute et 5 minutes, jusqu'à 4 tentatives |
410 | Désactive l'abonnement aussitôt |
Tout autre 4xx | Abandonne cette livraison |
Une livraison peut arriver plus d'une fois, et les événements peuvent arriver dans le désordre. Utilisez x-fs-delivery
pour ignorer les événements déjà traités, et createdAt pour les ordonner.
Si plus de 500 livraisons attendent pour un espace de travail, les nouveaux événements de cet espace ne sont pas mis en file.
Quand un abonnement est désactivé #
Tout essai qui ne reçoit pas de 2xx compte comme un échec : un délai dépassé, une erreur réseau ou tout autre statut. Un 2xx remet le compte à 0. Filmsquare désactive l'abonnement (active passe à false) quand :
- 5 essais de suite ou plus ont échoué et que le premier date d'au moins 10 minutes, ou
- votre URL a répondu
410, ou - votre URL est lente plus souvent qu'à son tour. Chaque réponse qui prend plus de 5 secondes, même un
2xx, ajoute 1 à un compte de lenteur, et chaque réponse plus rapide en retire 1 (jamais sous 0). À 20, l'abonnement est désactivé. Un délai dépassé ou une erreur réseau compte seulement comme un essai échoué, jamais comme une lenteur.
Une courte panne, comme un déploiement, ne le désactive pas. Les livraisons qui attendent encore pour un abonnement désactivé ne sont pas envoyées, et les propriétaires de l'espace de travail reçoivent une notification dans leur boîte de réception, au plus une fois par jour et par abonnement. L'abonnement indique pourquoi :
| Champ | Valeur |
|---|---|
consecutive_failures | Essais échoués de suite |
consecutive_slow | Le compte de lenteur : +1 pour chaque réponse de plus de 5 secondes, −1 pour chaque réponse plus rapide |
failing_since | Début de la série d'échecs en cours, ou null |
disabled_at | Moment de la désactivation, ou null |
disabled_reason | Raison de la désactivation, ou null |
Pour le réactiver, mettez le webhook à jour avec "active": true. Cela remet consecutive_failures et consecutive_slow à 0 et efface la raison. Un abonnement qui s'est désactivé de lui-même peut être réactivé 3 fois en 24 heures. Ensuite, la mise à jour répond 409 avec le code webhook_rearm_limit : réparez d'abord votre endpoint.