# Webhook Collection Sync | Docs AudioDN

> Le webhook Collection Sync notifie votre application chaque fois qu

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

---

# Webhook Collection Sync

Le webhook Collection Sync permet à votre application de rester synchronisée avec vos collections AudioDN. Chaque fois qu’une collection est créée, mise à jour ou supprimée, AudioDN envoie une requête HTTP `POST` à l’URL de webhook de collection configurée pour votre organisation. Ceci est distinct du [webhook Track Processing](/docs/webhooks/track-processing), qui couvre les changements de statut de piste.

#### Configuré dans le tableau de bord

L’URL du webhook de collection 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 création/mise à jour/suppression de collection pour votre organisation y est livrée. Laissez-la vide pour désactiver les webhooks de collection.

## Quand il se déclenche

Un webhook est livré chaque fois qu’une collection change d’état :

-   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 (par exemple `collection.updated`).
-   La livraison est fire-and-forget / au moins une fois — concevez votre gestionnaire pour être idempotent.
-   L’ordre des événements n’est pas garanti ; utilisez le `event` et le champ `updated_at` de la collection plutôt que d’assumer l’ordre d’arrivée.
-   Les requêtes sont actuellement non signées. Traitez l’URL du webhook comme un secret et, si besoin, vérifiez le `collection_id` auprès de l’API.
-   Répondez rapidement avec un code de statut `2xx` pour accuser réception.

## Événements

| Événement | Signification |
| --- | --- |
| collection.created | Une nouvelle collection a été créée. Envoyé une fois, lorsque la ligne de collection est d'abord insérée. |
| collection.updated | Une collection existante a changé — par exemple son titre, ses métadonnées, sa couverture ou ses paramètres de lecteur. |
| collection.deleted | Une collection a été supprimée. Envoyé lorsque la collection est retirée (ses pistes et fichiers sont retirés avec elle). |

## Schéma du payload

Chaque événement livre la même enveloppe. L’objet `collection` contient les champs actuels de la collection ; sur un événement `collection.deleted` il reflète la ligne supprimée (avec `deleted_at` défini).

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

## Images de couverture

Lorsqu’une collection a une pochette, `collection.cover_image` fournit des URL prêtes à l’emploi à chaque taille disponible (et `collection.cloudflare_image_id` stocke l’identifiant d’image si vous en avez besoin). Les deux sont `null` lorsqu’il n’y a pas de couverture. Préférez les URL toutes faites ; si vous n’avez que l’identifiant d’image, construisez n’importe quelle taille vous-même avec le modèle ci-dessous, où `<variant>` est `icon` (80x80), `small` (200x200), `regular` (400x400), ou `large` (800x800) :

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

Voir [Track Processing → Images de couverture](/docs/webhooks/track-processing#cover-images) pour la référence complète des variantes. Le même schéma est utilisé dans les réponses `cover_image` de l’API.

## Exemples de payloads

### Créée

Envoyé lorsqu’une nouvelle collection est créée.

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

### Mise à jour

Envoyé lorsque les champs d’une collection changent.

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

### Supprimée

Envoyé lorsqu’une collection est supprimée. Le champ `deleted_at` est renseigné.

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

#### 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 de collection dans Settings est correcte.

## Gestion des webhooks

Un gestionnaire minimal lit le champ `event` et garde votre copie locale de la collection synchronisée. Parce que la livraison est au moins une fois et non ordonnée, cléz votre logique sur `collection_id` et le `updated_at` de la collection plutôt que sur l’ordre de réception.

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