Webhook Track File

Le webhook Track File permet à votre application de réagir aux fichiers de piste 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, 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 et 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 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)
}
})