# Webhook Track File | Docs AudioDN

> Le webhook Track File notifie votre application des fichiers de piste individuels à mesure qu

Source: https://audiodeliverynetwork.com/fr/docs/webhooks/track-files/

---

# Webhook Track File

Le webhook Track File permet à votre application de réagir aux [fichiers de piste](/docs) individuels à mesure qu’ils sont produits. Chaque fichier de piste est le résultat de l’application d’une variante (recette) à une piste. Au lieu de recevoir le tableau `files[]` complet à chaque [changement de statut de piste](/docs/webhooks/track-processing), ce webhook livre **un fichier de piste à la fois** — ce qui est plus facile à gérer lorsqu’une piste a de nombreuses variantes.

#### Configuré dans le tableau de bord

L’URL du webhook Track File est définie dans votre panneau **Settings → Webhook** du tableau de bord, pas via l’API. Une fois qu’une URL est enregistrée, chaque événement de fichier de piste pour votre organisation y est livré. Laissez-la vide pour le désactiver. Ceci est indépendant des webhooks [Track Processing](/docs/webhooks/track-processing) et [Collection Sync](/docs/webhooks/collection-sync) — activez ceux dont vous avez besoin.

## Quand il se déclenche

Une piste produit normalement plusieurs fichiers de piste (un par variante). Ce webhook se déclenche **une fois par fichier de piste** plutôt qu’une fois par piste. Chaque fichier de piste — qu’il réussisse ou échoue — est enregistré, donc vous obtenez toujours exactement un événement par fichier. Chaque payload porte un `status` (`success` ou `failed`) et un `event` correspondant :

| Résultat | Événement | Statut | Signification |
| --- | --- | --- | --- |
| Créé avec succès | track\_file.created | success | Un fichier de piste a terminé le traitement et a été stocké. L'envoi vers le stockage est déjà terminé, donc cet événement marque le fichier comme disponible. L'objet fichier a file.is\_success = true. |
| Échoué | track\_file.failed | failed | Une variante a échoué au traitement. Une ligne de fichier est quand même livrée pour que le mapping reste 1:1, mais avec file.is\_success = false, pas d'url, et la raison dans message. |

-   Envoyé comme un HTTP `POST` avec `Content-Type: application/json`.
-   Inclut un en-tête `X-ADN-Event` défini au nom de l’événement (`track_file.created` ou `track_file.failed`).
-   Branchez-vous sur le `status` de premier niveau (`success` / `failed`) ou sur `file.is_success`.
-   La livraison est fire-and-forget / au moins une fois — concevez votre gestionnaire pour être idempotent (clé sur `file_id`, ou sur `track_id` + `variant.index`).
-   L’ordre des événements n’est pas garanti entre les fichiers.
-   Les requêtes sont actuellement non signées. Traitez l’URL du webhook comme un secret et, si besoin, vérifiez le `track_id` auprès de l’API.
-   Répondez rapidement avec un code de statut `2xx` pour accuser réception.

#### Track File vs Track Processing

Utilisez le [webhook Track Processing](/docs/webhooks/track-processing) pour réagir au cycle de vie global d’une piste (`processing` → `ready`). Utilisez le webhook Track File lorsque vous vous souciez de chaque fichier de sortie individuel à mesure qu’il arrive — par exemple, pour débloquer un téléchargement lossless acheté dès qu’il est prêt, sans attendre que toute la piste soit terminée.

## Schéma du payload

L’objet `file` correspond à une seule entrée du tableau `files[]` livré par le webhook Track Processing, y compris la `variant` imbriquée (recette) qui l’a produit, plus `is_success`. Le succès et l’échec livrent tous deux un objet `file`. En cas d’échec, `file.is_success` est `false`, `file.url` est `null` (aucun objet n’a été stocké), et la raison est dans le `message` de premier niveau (reflété dans `file.status_text`).

```
{
"event": "track_file.created | track_file.failed",
"status": "success | failed",
"organization_id": "uuid",
"creator_id": "uuid | null",
"collection_id": "uuid",
"track_id": "uuid",
"file_id": "uuid",
"message": "string | null",
"file": {
  "id": "uuid",
  "path": "string",
  "url": "string | null",
  "size": "number | null",
  "content_type": "string | null",
  "file_name": "string",
  "is_public": "boolean",
  "is_success": "boolean",
  "status_text": "string | null",
  "data": "object | null",
  "props": "object | null",
  "variant": {
    "id": "uuid",
    "index": "string",
    "variant_type": {
      "id": "string",
      "viewer_id": "string",
      "title": "string"
    }
  }
}
}
```

Lisez la variante qui a produit (ou aurait produit) le fichier depuis `file.variant`. En cas de succès, `message` est `null` et `file.url` pointe vers l’objet stocké. En cas d’échec, `message` contient l’erreur, `file.url` est `null`, et `file.size` / `file.content_type` peuvent être `null`.

## Exemples de payloads

### Créé avec succès

Envoyé lorsqu’un fichier de piste termine le traitement et est stocké.

```
{
"event": "track_file.created",
"status": "success",
"organization_id": "11111111-1111-1111-1111-111111111111",
"creator_id": null,
"collection_id": "22222222-2222-2222-2222-222222222222",
"track_id": "33333333-3333-3333-3333-333333333333",
"file_id": "55555555-5555-5555-5555-555555555555",
"message": null,
"file": {
  "id": "55555555-5555-5555-5555-555555555555",
  "path": "org/collection/track/transcode.aac",
  "url": "https://cdn.audiodn.com/org/collection/track/transcode.aac",
  "size": 17012344,
  "content_type": "audio/aac",
  "file_name": "transcode.aac",
  "is_public": true,
  "is_success": true,
  "status_text": "OK",
  "data": null,
  "props": null,
  "variant": {
    "id": "66666666-6666-6666-6666-666666666666",
    "index": "transcode-default",
    "variant_type": {
      "id": "transcode",
      "viewer_id": "audio",
      "title": "Transcoded Audio"
    }
  }
}
}
```

### Échoué (erreur de variante)

Envoyé lorsqu’une variante échoue au traitement. Une ligne `file` est quand même livrée (pour que le mapping reste 1:1), mais avec `is_success: false`, pas d’`url`, et la raison dans `message`.

```
{
"event": "track_file.failed",
"status": "failed",
"organization_id": "11111111-1111-1111-1111-111111111111",
"creator_id": null,
"collection_id": "22222222-2222-2222-2222-222222222222",
"track_id": "33333333-3333-3333-3333-333333333333",
"file_id": "77777777-7777-7777-7777-777777777777",
"message": "ffmpeg exited with code 1: unsupported sample format",
"file": {
  "id": "77777777-7777-7777-7777-777777777777",
  "path": "org/collection/track/preview-30s.aac",
  "url": null,
  "size": null,
  "content_type": "audio/aac",
  "file_name": "preview-30s.aac",
  "is_public": false,
  "is_success": false,
  "status_text": "ffmpeg exited with code 1: unsupported sample format",
  "data": null,
  "props": null,
  "variant": {
    "id": "66666666-6666-6666-6666-666666666666",
    "index": "preview-30s",
    "variant_type": {
      "id": "preview",
      "viewer_id": "audio",
      "title": "Preview Clip"
    }
  }
}
}
```

#### Vérification de la livraison

Chaque tentative de livraison est journalisée côté AudioDN, y compris le code de statut HTTP renvoyé par votre point de terminaison. Si vous cessez de recevoir des événements, confirmez que votre point de terminaison renvoie rapidement une réponse `2xx` et que l’URL du webhook Track File dans Settings est correcte.

## Gestion des webhooks

Branchez-vous sur `status` (ou `file.is_success`). Parce que la livraison est au moins une fois et non ordonnée, cléz votre logique sur `file_id` (ou `track_id` + `file.variant.index`) plutôt que sur l’ordre de réception.

```
app.post('/webhooks/audiodn/track-files', (req, res) => {
// Acknowledge quickly, then process asynchronously.
res.sendStatus(200)

const { status, track_id, file, message } = req.body
if (status === 'success') {
  // A single track file is ready — store or unlock it.
  saveTrackFile(track_id, file)
} else {
  // A variant failed — file.is_success is false and file.url is null.
  flagVariantFailure(track_id, file.variant, message)
}
})
```