Webhook Track File

El webhook Track File permite que tu aplicación reaccione a track files individuales a medida que se producen. Cada track file es el resultado de aplicar una variante (receta) a una pista. En lugar de recibir el array completo files[] en cada cambio de estado de pista, este webhook entrega un track file a la vez — lo cual es más fácil de manejar cuando una pista tiene muchas variantes.

Se configura en el panel

La URL del webhook Track File se establece en el panel Settings → Webhook del dashboard, no vía la API. Una vez guardada una URL, cada evento de track file de tu organización se entrega a ella. Déjala en blanco para desactivarlo. Es independiente de los webhooks Track Processing y Collection Sync — habilita los que necesites.

Cuándo se dispara

Una pista normalmente produce varios track files (uno por variante). Este webhook se dispara una vez por track file en lugar de una vez por pista. Cada track file — tanto si tiene éxito como si falla — se registra, así que siempre obtienes exactamente un evento por archivo. Cada payload lleva un status (success o failed) y un event coincidente:

Resultado	Evento	Estado	Significado
Creado con éxito	track_file.created	success	Un track file terminó de procesarse y se almacenó. La subida al almacenamiento ya se ha completado, así que este evento marca el archivo como disponible. El objeto file tiene file.is_success = true.
Fallido	track_file.failed	failed	Una variante falló al procesarse. Aun así se entrega una fila de file para que el mapeo se mantenga 1:1, pero con file.is_success = false, sin url y el motivo en message.

Se envía como un HTTP POST con Content-Type: application/json.
Incluye una cabecera X-ADN-Event con el nombre del evento (track_file.created o track_file.failed).
Ramifica según el status de nivel superior (success / failed) o según file.is_success.
La entrega es fire-and-forget / al menos una vez — diseña tu manejador para que sea idempotente (clave en file_id, o en track_id + variant.index).
No se garantiza el orden de eventos entre archivos.
Las solicitudes actualmente no están firmadas. Trata la URL del webhook como un secreto y, si hace falta, verifica el track_id contra la API.
Responde con prontitud con un código de estado 2xx para acusar recibo.

Track File vs Track Processing

Usa el webhook Track Processing para reaccionar al ciclo de vida general de una pista (processing → ready). Usa el webhook Track File cuando te importe cada archivo de salida individual a medida que llega — por ejemplo, para desbloquear una descarga lossless comprada en el momento en que esté lista, sin esperar a que termine toda la pista.

Esquema del payload

El objeto file coincide con una sola entrada del array files[] entregado por el webhook Track Processing, incluyendo la variant anidada (receta) que lo produjo, más is_success. Tanto el éxito como el fallo entregan un objeto file. En caso de fallo, file.is_success es false, file.url es null (no se almacenó ningún objeto) y el motivo está en el message de nivel superior (reflejado en 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"
    }
  }
}
}

Lee la variante que produjo (o habría producido) el archivo desde file.variant. En caso de éxito, message es null y file.url apunta al objeto almacenado. En caso de fallo, message contiene el error, file.url es null, y file.size / file.content_type pueden ser null.

Ejemplos de payload

Creado con éxito

Se envía cuando un track file termina de procesarse y se almacena.

{
"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"
    }
  }
}
}

Fallido (error de variante)

Se envía cuando una variante falla al procesarse. Aun así se entrega una fila file (para que el mapeo se mantenga 1:1), pero con is_success: false, sin url y el motivo en 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"
    }
  }
}
}

Verificar la entrega

Cada intento de entrega se registra en el lado de AudioDN, incluyendo el código de estado HTTP devuelto por tu endpoint. Si dejas de recibir eventos, confirma que tu endpoint responde con 2xx rápidamente y que la URL del webhook Track File en Settings es correcta.

Manejar webhooks

Ramifica según status (o file.is_success). Como la entrega es al menos una vez y sin orden garantizado, basa tu lógica en file_id (o track_id + file.variant.index) en lugar del orden de recepción.

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)
}
})