# Collection-Sync-Webhook | AudioDN Docs

> Der Collection-Sync-Webhook informiert Ihre Anwendung, wenn eine Sammlung erstellt, aktualisiert oder gelöscht wird.

Source: https://audiodeliverynetwork.com/de/docs/webhooks/collection-sync/

---

# Collection-Sync-Webhook

Der Collection-Sync-Webhook hält Ihre Anwendung mit Ihren AudioDN-Sammlungen synchron. Jedes Mal, wenn eine Sammlung erstellt, aktualisiert oder gelöscht wird, sendet AudioDN eine HTTP-`POST`\-Anfrage an die für Ihre Organisation konfigurierte Sammlungs-Webhook-URL. Dies ist unabhängig vom [Track-Processing-Webhook](/docs/webhooks/track-processing), der Track-Statuswechsel abdeckt.

#### Im Dashboard konfiguriert

Die Sammlungs-Webhook-URL wird in Ihrem **Settings → Webhook**\-Bereich im Dashboard festgelegt, nicht über die API. Sobald eine URL gespeichert ist, wird jedes Erstellen/Aktualisieren/Löschen einer Sammlung Ihrer Organisation an sie ausgeliefert. Lassen Sie das Feld leer, um Sammlungs-Webhooks zu deaktivieren.

## Wann er ausgelöst wird

Ein Webhook wird immer dann zugestellt, wenn sich der Zustand einer Sammlung ändert:

-   Wird als HTTP-`POST` mit `Content-Type: application/json` gesendet.
-   Enthält einen `X-ADN-Event`\-Header, gesetzt auf den Ereignisnamen (zum Beispiel `collection.updated`).
-   Die Zustellung erfolgt nach dem Prinzip „fire-and-forget“ / mindestens einmal — gestalten Sie Ihren Handler idempotent.
-   Die Reihenfolge der Ereignisse ist nicht garantiert; verlassen Sie sich auf das Feld `event` und das `updated_at`\-Feld der Sammlung statt auf die Ankunftsreihenfolge.
-   Anfragen sind derzeit unsigniert. Behandeln Sie die Webhook-URL als Geheimnis und prüfen Sie bei Bedarf die `collection_id` gegen die API.
-   Antworten Sie zeitnah mit einem `2xx`\-Statuscode, um den Empfang zu bestätigen.

## Ereignisse

| Ereignis | Bedeutung |
| --- | --- |
| collection.created | Eine neue Sammlung wurde erstellt. Wird einmal gesendet, wenn die Sammlungszeile erstmals eingefügt wird. |
| collection.updated | Eine bestehende Sammlung hat sich geändert — zum Beispiel Titel, Metadaten, Cover oder Player-Einstellungen. |
| collection.deleted | Eine Sammlung wurde gelöscht. Wird gesendet, wenn die Sammlung entfernt wird (ihre Tracks und Dateien werden mit ihr entfernt). |

## Payload-Schema

Jedes Ereignis liefert die gleiche Umschlagstruktur. Das `collection`\-Objekt enthält die aktuellen Felder der Sammlung; bei einem `collection.deleted`\-Ereignis spiegelt es die gelöschte Zeile wider (mit gesetztem `deleted_at`).

```
{
"event": "collection.created | collection.updated | collection.deleted",
"organization_id": "uuid",
"creator_id": "uuid | null",
"collection_id": "uuid",
"collection": {
  "id": "uuid",
  "organization_id": "uuid",
  "creator_id": "uuid | null",
  "title": "string | null",
  "organization_index": "string | null",
  "metadata": "object | null",
  "theme": "array | null",
  "player_color": "string | null",
  "player_color_light": "string | null",
  "player_color_dark": "string | null",
  "player_subtitle": "string | null",
  "is_cover_overridable": "boolean",
  "is_theme_overridable": "boolean",
  "cloudflare_image_id": "uuid | null",
  "cover_image": {
    "icon": { "type": "icon", "width": 80, "height": 80, "url": "string" },
    "small": { "type": "small", "width": 200, "height": 200, "url": "string" },
    "regular": { "type": "regular", "width": 400, "height": 400, "url": "string" },
    "large": { "type": "large", "width": 800, "height": 800, "url": "string" }
  },
  "created_at": "string",
  "updated_at": "string",
  "deleted_at": "string | null"
}
}
```

## Coverbilder

Wenn eine Sammlung Cover-Artwork besitzt, liefert `collection.cover_image` gebrauchsfertige URLs für jede verfügbare Größe (und `collection.cloudflare_image_id` speichert die Bild-ID, falls Sie sie benötigen). Beide sind `null`, wenn kein Cover vorhanden ist. Bevorzugen Sie die vorgefertigten URLs; falls Sie nur die Bild-ID haben, können Sie jede Größe selbst nach dem folgenden Muster erzeugen, wobei `<variant>` für `icon` (80x80), `small` (200x200), `regular` (400x400) oder `large` (800x800) steht:

```
https://imagedelivery.net/iVHDyjXAr_lt5UUJaLbk1Q/{cloudflare_image_id}/{variant}
```

Die vollständige Übersicht der Varianten finden Sie unter [Track Processing → Coverbilder](/docs/webhooks/track-processing#cover-images). Dasselbe Schema wird in den `cover_image`\-Antworten der gesamten API verwendet.

## Beispiel-Payloads

### Erstellt

Wird gesendet, wenn eine neue Sammlung erstellt wird.

```
{
"event": "collection.created",
"organization_id": "11111111-1111-1111-1111-111111111111",
"creator_id": null,
"collection_id": "22222222-2222-2222-2222-222222222222",
"collection": {
  "id": "22222222-2222-2222-2222-222222222222",
  "organization_id": "11111111-1111-1111-1111-111111111111",
  "creator_id": null,
  "title": "Season 1",
  "organization_index": "your-collection-id-001",
  "metadata": null,
  "theme": null,
  "player_color": "#1DB954",
  "player_color_light": "#1BAA4D",
  "player_color_dark": "#1DB954",
  "player_subtitle": "Acme Media",
  "is_cover_overridable": true,
  "is_theme_overridable": true,
  "cloudflare_image_id": null,
  "cover_image": null,
  "created_at": "2026-07-02T10:00:00.000Z",
  "updated_at": "2026-07-02T10:00:00.000Z",
  "deleted_at": null
}
}
```

### Aktualisiert

Wird gesendet, wenn sich Felder einer Sammlung ändern.

```
{
"event": "collection.updated",
"organization_id": "11111111-1111-1111-1111-111111111111",
"creator_id": null,
"collection_id": "22222222-2222-2222-2222-222222222222",
"collection": {
  "id": "22222222-2222-2222-2222-222222222222",
  "organization_id": "11111111-1111-1111-1111-111111111111",
  "creator_id": null,
  "title": "Season 1 (Remastered)",
  "organization_index": "your-collection-id-001",
  "metadata": { "genre": "podcast" },
  "theme": null,
  "player_color": "#1DB954",
  "player_color_light": "#1BAA4D",
  "player_color_dark": "#1DB954",
  "player_subtitle": "Acme Media",
  "is_cover_overridable": true,
  "is_theme_overridable": true,
  "cloudflare_image_id": "99999999-9999-9999-9999-999999999999",
  "cover_image": {
    "icon": { "type": "icon", "width": 80, "height": 80, "url": "https://imagedelivery.net/iVHDyjXAr_lt5UUJaLbk1Q/99999999-9999-9999-9999-999999999999/icon" },
    "small": { "type": "small", "width": 200, "height": 200, "url": "https://imagedelivery.net/iVHDyjXAr_lt5UUJaLbk1Q/99999999-9999-9999-9999-999999999999/small" },
    "regular": { "type": "regular", "width": 400, "height": 400, "url": "https://imagedelivery.net/iVHDyjXAr_lt5UUJaLbk1Q/99999999-9999-9999-9999-999999999999/regular" },
    "large": { "type": "large", "width": 800, "height": 800, "url": "https://imagedelivery.net/iVHDyjXAr_lt5UUJaLbk1Q/99999999-9999-9999-9999-999999999999/large" }
  },
  "created_at": "2026-07-02T10:00:00.000Z",
  "updated_at": "2026-07-02T12:30:00.000Z",
  "deleted_at": null
}
}
```

### Gelöscht

Wird gesendet, wenn eine Sammlung gelöscht wird. Das Feld `deleted_at` ist dann gesetzt.

```
{
"event": "collection.deleted",
"organization_id": "11111111-1111-1111-1111-111111111111",
"creator_id": null,
"collection_id": "22222222-2222-2222-2222-222222222222",
"collection": {
  "id": "22222222-2222-2222-2222-222222222222",
  "organization_id": "11111111-1111-1111-1111-111111111111",
  "creator_id": null,
  "title": "Season 1 (Remastered)",
  "organization_index": "your-collection-id-001",
  "metadata": { "genre": "podcast" },
  "theme": null,
  "player_color": "#1DB954",
  "player_color_light": "#1BAA4D",
  "player_color_dark": "#1DB954",
  "player_subtitle": "Acme Media",
  "is_cover_overridable": true,
  "is_theme_overridable": true,
  "cloudflare_image_id": "99999999-9999-9999-9999-999999999999",
  "cover_image": {
    "icon": { "type": "icon", "width": 80, "height": 80, "url": "https://imagedelivery.net/iVHDyjXAr_lt5UUJaLbk1Q/99999999-9999-9999-9999-999999999999/icon" },
    "small": { "type": "small", "width": 200, "height": 200, "url": "https://imagedelivery.net/iVHDyjXAr_lt5UUJaLbk1Q/99999999-9999-9999-9999-999999999999/small" },
    "regular": { "type": "regular", "width": 400, "height": 400, "url": "https://imagedelivery.net/iVHDyjXAr_lt5UUJaLbk1Q/99999999-9999-9999-9999-999999999999/regular" },
    "large": { "type": "large", "width": 800, "height": 800, "url": "https://imagedelivery.net/iVHDyjXAr_lt5UUJaLbk1Q/99999999-9999-9999-9999-999999999999/large" }
  },
  "created_at": "2026-07-02T10:00:00.000Z",
  "updated_at": "2026-07-02T13:00:00.000Z",
  "deleted_at": "2026-07-02T13:00:00.000Z"
}
}
```

#### 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 Sammlungs-Webhook-URL in den Settings korrekt ist.

## Webhooks verarbeiten

Ein minimaler Handler liest das Feld `event` und hält Ihre lokale Kopie der Sammlung synchron. Da die Zustellung mindestens einmal und ungeordnet erfolgt, sollten Sie Ihre Logik auf `collection_id` und das `updated_at`\-Feld der Sammlung stützen statt auf die Empfangsreihenfolge.

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

const { event, collection_id, collection } = req.body

switch (event) {
  case 'collection.created':
  case 'collection.updated':
    // Upsert your local copy of the collection.
    upsertCollection(collection_id, collection)
    break
  case 'collection.deleted':
    // Remove your local copy.
    removeCollection(collection_id)
    break
}
})
```