Track-File-Webhook

Der Track-File-Webhook ermöglicht es Ihrer Anwendung, auf einzelne Track-Dateien zu reagieren, sobald sie erzeugt werden. Jede Track-Datei ist das Ergebnis der Anwendung einer Variante (Rezept) auf einen Track. Statt bei jedem Track-Statuswechsel das vollständige files[]-Array zu erhalten, liefert dieser Webhook jeweils eine Track-Datei — das ist einfacher zu handhaben, wenn ein Track viele Varianten hat.

Im Dashboard konfiguriert

Die URL des Track-File-Webhooks wird in Ihrem Settings → Webhook-Bereich im Dashboard festgelegt, nicht über die API. Sobald eine URL gespeichert ist, wird jedes Track-File-Ereignis Ihrer Organisation an sie ausgeliefert. Lassen Sie das Feld leer, um den Webhook zu deaktivieren. Dies ist unabhängig von den Webhooks Track Processing und Collection Sync — aktivieren Sie, was Sie benötigen.

Wann er ausgelöst wird

Ein Track erzeugt normalerweise mehrere Track-Dateien (eine pro Variante). Dieser Webhook wird einmal pro Track-Datei ausgelöst, nicht einmal pro Track. Jede Track-Datei — ob erfolgreich oder fehlgeschlagen — wird erfasst, sodass Sie stets genau ein Ereignis pro Datei erhalten. Jeder Payload trägt einen status (success oder failed) und ein passendes event:

Ergebnis	Ereignis	Status	Bedeutung
Erfolgreich erstellt	track_file.created	success	Eine Track-Datei wurde vollständig verarbeitet und gespeichert. Der Upload in den Speicher ist bereits abgeschlossen, daher markiert dieses Ereignis die Datei als verfügbar. Das Datei-Objekt hat file.is_success = true.
Fehlgeschlagen	track_file.failed	failed	Eine Variante konnte nicht verarbeitet werden. Es wird trotzdem eine Datei-Zeile geliefert, damit die Zuordnung 1:1 bleibt, jedoch mit file.is_success = false, ohne url und mit dem Grund in message.

Wird als HTTP-POST mit Content-Type: application/json gesendet.
Enthält einen X-ADN-Event-Header, gesetzt auf den Ereignisnamen (track_file.created oder track_file.failed).
Werten Sie den obersten status (success / failed) oder file.is_success aus.
Die Zustellung erfolgt nach dem Prinzip „fire-and-forget“ / mindestens einmal — gestalten Sie Ihren Handler idempotent (Schlüssel auf file_id oder auf track_id + variant.index).
Die Reihenfolge der Ereignisse ist zwischen Dateien nicht garantiert.
Anfragen sind derzeit unsigniert. Behandeln Sie die Webhook-URL als Geheimnis und prüfen Sie bei Bedarf die track_id gegen die API.
Antworten Sie zeitnah mit einem 2xx-Statuscode, um den Empfang zu bestätigen.

Track File vs. Track Processing

Verwenden Sie den Track-Processing-Webhook, um auf den gesamten Lebenszyklus eines Tracks (processing → ready) zu reagieren. Verwenden Sie den Track-File-Webhook, wenn Sie sich für jede einzelne Ausgabedatei interessieren, sobald sie eintrifft — zum Beispiel, um einen gekauften verlustfreien Download in dem Moment freizuschalten, in dem er fertig ist, ohne auf den Abschluss des gesamten Tracks zu warten.

Payload-Schema

Das file-Objekt entspricht einem einzelnen Eintrag des files[]-Arrays, das vom Track-Processing-Webhook geliefert wird, einschließlich der verschachtelten variant (Rezept), die es erzeugt hat, sowie is_success. Sowohl Erfolg als auch Fehlschlag liefern ein file-Objekt. Bei einem Fehlschlag ist file.is_success false, file.url ist null (es wurde kein Objekt gespeichert), und der Grund steht in der obersten message (gespiegelt in 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"
    }
  }
}
}

Entnehmen Sie file.variant, welche Variante die Datei erzeugt hat (oder erzeugt hätte). Bei Erfolg ist message null und file.url zeigt auf das gespeicherte Objekt. Bei einem Fehlschlag enthält message den Fehler, file.url ist null, und file.size / file.content_type können null sein.

Beispiel-Payloads

Erfolgreich erstellt

Wird gesendet, wenn eine Track-Datei die Verarbeitung abgeschlossen hat und gespeichert wurde.

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

Fehlgeschlagen (Variantenfehler)

Wird gesendet, wenn eine Variante nicht verarbeitet werden konnte. Es wird trotzdem eine file-Zeile geliefert (damit die Zuordnung 1:1 bleibt), jedoch mit is_success: false, ohne url und mit dem Grund in 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"
    }
  }
}
}

Zustellung überprüfen

Jeder Zustellversuch wird auf Seiten von AudioDN protokolliert, einschließlich des von Ihrem Endpunkt zurückgegebenen HTTP-Statuscodes. Wenn Sie keine Ereignisse mehr erhalten, prüfen Sie, ob Ihr Endpunkt zügig eine 2xx-Antwort zurückgibt und ob die Track-File-Webhook-URL in den Settings korrekt ist.

Webhooks verarbeiten

Werten Sie status (oder file.is_success) aus. Da die Zustellung mindestens einmal und ungeordnet erfolgt, sollten Sie Ihre Logik auf file_id (oder track_id + file.variant.index) stützen statt auf die Empfangsreihenfolge.

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