# Track-File-Webhook | AudioDN Docs

> Der Track-File-Webhook informiert Ihre Anwendung über einzelne Track-Dateien, sobald sie erstellt werden oder fehlschlagen — eine Datei nach der anderen, statt den vollständigen Track-Payload auspacken zu müssen.

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

---

# Track-File-Webhook

Der Track-File-Webhook ermöglicht es Ihrer Anwendung, auf einzelne [Track-Dateien](/docs) 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](/docs/webhooks/track-processing) 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](/docs/webhooks/track-processing) und [Collection Sync](/docs/webhooks/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](/docs/webhooks/track-processing), 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)
}
})
```