Webhooks

Webhooks notify your application when processing finishes or collections change. They complement Web Components and the REST API — they do not replace upload or playback.

When to use them

  • Update your database when a track becomes playable
  • Unlock a specific output (for example a lossless download or VTT file) as soon as it is ready
  • Keep an external catalog in sync with collection create/update/delete

Which webhook to enable

Track Processing

Fires on

Terminal track status (ready, incomplete, error, init_error) and when the full output set finishes (files_completed_at).

Use when you care about track-level readiness or overall completion — including track fields like transcription.

track.status_changed

Reference →

Outputs

Fires on

Each individual output as it succeeds or fails — one delivery per output, not per track.

Use when you unlock a file the moment it lands (lossless download, WebVTT, waveform) without waiting for the whole track.

track_file.created · track_file.failed

Reference →

Collection Sync

Fires on

Collection create, update, and delete in your organization.

Use when you mirror AudioDN collections into another catalog or CMS.

collection.created · updated · deleted

Reference →

Caption .vtt files are normal outputs — use the Output webhook (or a play session) when that file is ready. Plain-text transcription lives on the track and arrives with Track Processing.

Minimal receiver

Acknowledge quickly with 2xx, then branch on the event. Treat the webhook URL as a secret (requests are unsigned today), and keep handlers idempotent — delivery can repeat and order is not guaranteed.

import express from 'express';

const app = express();
app.use(express.json());

app.post('/webhooks/audiodn', async (req, res) => {
const event = req.get('X-ADN-Event') || req.body.event;
res.status(200).end();

switch (event) {
  case 'track.status_changed': {
    const { track_id, status, track } = req.body;
    break;
  }
  case 'track_file.created':
  case 'track_file.failed': {
    const { track_id, file_id, status, file } = req.body;
    break;
  }
  case 'collection.created':
  case 'collection.updated':
  case 'collection.deleted': {
    const { collection_id } = req.body;
    break;
  }
  default:
    break;
}
});

Payload schemas: Track Processing · Outputs · Collection Sync