Receive terminal audio separation events when a queued request completes, fails, or is canceled.

Pass webhookUrl when submitting a job if your backend should receive a terminal callback.

Webhooks are optional. Use polling when you want the simplest integration. Use webhooks for backend workflows where the caller may not stay online while the job runs.

{
  "input": {
    "audio_url": "https://example.com/audio.wav",
    "prompt": "isolate the lead vocal"
  },
  "webhookUrl": "https://example.com/webhooks/audiolasso",
  "webhookSecret": "replace-with-your-hmac-secret"
}

Completed event

{
  "type": "audio.separate.completed",
  "request_id": "req_01jabc",
  "model": "audio/separate",
  "status": "COMPLETED",
  "data": {
    "target": {
      "url": "https://...",
      "content_type": "audio/wav",
      "file_name": "target.wav"
    },
    "residual": {
      "url": "https://...",
      "content_type": "audio/wav",
      "file_name": "residual.wav"
    }
  }
}

Failed event

{
  "type": "audio.separate.failed",
  "request_id": "req_01jabc",
  "model": "audio/separate",
  "status": "FAILED",
  "error": {
    "code": "MODEL_FAILED",
    "message": "The model failed to process the audio."
  }
}

Canceled event

{
  "type": "audio.separate.canceled",
  "request_id": "req_01jabc",
  "model": "audio/separate",
  "status": "CANCELED",
  "error": {
    "code": "REQUEST_CANCELED",
    "message": "Request canceled by the client."
  }
}

Delivery behavior

Return any 2xx status to acknowledge delivery. Non-2xx responses are treated as delivery failures.

Handle webhook events idempotently with request_id. If delivery is delayed or fails, the status and result endpoints remain the source of truth.

Verify with the TypeScript SDK

Read the raw body before parsing JSON, then pass the signature headers to the SDK. The default replay window is five minutes.

import { verifyWebhookSignature } from "audiolasso";

const body = await request.text();
const valid = await verifyWebhookSignature({
  body,
  secret: process.env.AUDIOLASSO_WEBHOOK_SECRET!,
  signature: request.headers.get("AudioLasso-Signature") ?? "",
  timestamp: request.headers.get("AudioLasso-Timestamp") ?? "",
});

if (!valid) return new Response("Invalid signature", { status: 401 });
const event = JSON.parse(body);