---
title: "Webhooks"
description: "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."
url: https://www.filmsquare.ai/docs/fr/api/webhooks/
lang: fr
section: api
updated: 2026-11-17
---

# Webhooks

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

```bash
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"]}'
```

```json
{"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_…"}
```

> [!NOTE]
> Le `secret` n'est renvoyé qu'ici. Conservez-le : il vous sert à vérifier chaque livraison.

- `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`.

| 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 :

```http
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.

```js
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.

## À lire aussi

- [Aperçu de l'API et clés](https://www.filmsquare.ai/docs/fr/api/overview/)
- [Référence OpenAPI](https://www.filmsquare.ai/docs/fr/api/openapi/)
