Filmsquare AideDocs

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.

Mis à jour 4 min de lecture.md

Sur cette page
  1. S'abonner
  2. Événements
  3. La livraison
  4. Les données de chaque événement
  5. Vérifier la signature
  6. Répondre et nouvelles tentatives
  7. Quand un abonnement est désactivé
  8. À lire aussi

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_…"}
  • events est une liste de types d'événements, ou ["*"] pour tous.
  • url doit être une adresse http ou https sur 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 409 avec le code webhook_limit.
RouteFait
GET /workspaces/{ws}/webhooksListe les abonnements (sans secrets)
POST /workspaces/{ws}/webhooksS'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 #

TypeEnvoyé quand
generation.succeededLe rendu d'une prise est terminé
generation.failedUn rendu a échoué (aussi quand Filmsquare le relance de lui-même)
take.selectedUne prise a été retenue sur un plan ou une séquence
asset_version.createdUn 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êteValeur
x-fs-signaturesha256= + le HMAC-SHA256 hexadécimal du corps brut, avec votre secret comme clé
x-fs-eventLe type d'événement
x-fs-deliveryL'id de l'événement. Le même événement a toujours le même id

Les données de chaque événement #

TypeChamps de data
generation.succeededgenerationId, takeId, shotId, sceneId, elementId, kind, tier, provider, modelKey, costCredits, assetVersionIds
generation.failedgenerationId, takeId, tier, attempt, error, retryGenerationId (la tentative suivante automatique, ou null)
take.selectedselectionId, takeId, assetVersionId, shotId, sceneId, kind, selectedBy
asset_version.createdassetVersionId, 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éponseCe que fait Filmsquare
2xxTerminé
5xx, 429, un délai dépassé ou une erreur réseauRéessaie après environ 10 secondes, 1 minute et 5 minutes, jusqu'à 4 tentatives
410Désactive l'abonnement aussitôt
Tout autre 4xxAbandonne 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 :

ChampValeur
consecutive_failuresEssais échoués de suite
consecutive_slowLe compte de lenteur : +1 pour chaque réponse de plus de 5 secondes, −1 pour chaque réponse plus rapide
failing_sinceDébut de la série d'échecs en cours, ou null
disabled_atMoment de la désactivation, ou null
disabled_reasonRaison 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.

Cette page en Markdown: /docs/fr/api/webhooks.md