Webhooks

AudioShake sends a POST request to your webhook URL each time a Task’s Target changes status. The payload is the full Task object, identical to the response from Get Task by ID.

Setup

You can configure a webhook URL in two ways:

Globally — set a default webhook URL in the AudioShake Dashboard under Settings > Webhook URL. It applies to every Task on your account.
Per Task — set webhookUrl in the body of your Create Task request. This applies to that Task only.

A webhookUrl set on a Task overrides the global webhook URL configured in the dashboard for that Task. If no webhookUrl is provided on the Task, the global dashboard URL is used.

Per-Task webhook example

curl --location 'https://api.audioshake.ai/tasks' \
--header 'Content-Type: application/json' \
--header 'x-api-key: YOUR_API_KEY' \
--data '{
    "url": "https://demos.audioshake.ai/demo-assets/shakeitup.mp3",
    "webhookUrl": "https://your-server.com/webhooks/audioshake",
    "targets": [
        {
            "model": "vocals",
            "formats": ["mp3"]
        },
        {
            "model": "instrumental",
            "formats": ["mp3"]
        }
    ]
}'

When webhooks fire

A webhook is sent each time a Target completes or errors. There is no callback when a Target is first created or begins processing — the first webhook you receive for a given Target will be completed or error.

Webhooks fire per Target, not once per Task. If a Task has three targets, you will receive up to three webhook requests.

Target status reference

Status	Meaning	What to do
`processing`	Target is actively being processed	No webhook is sent for this state — wait for `completed` or `error`
`completed`	Results are ready	Download files from the `output[].link` fields
`error`	Processing failed	Check the `error` field for details

Note: other targets in the same Task may still show processing when the webhook fires — this is expected.

Payload

The payload contains the full Task object. Each target includes its current status — some may be completed while others are still processing:

{
  "id": "cmn5h1wv600edx8fgoboeeg06",
  "createdAt": "2026-03-25T03:16:17.442Z",
  "clientId": "cm4lousna0yurbk8ngu31n8bb",
  "assetId": "cmn5gz2s800xp01phe9v3bm5r",
  "targets": [
    {
      "id": "cmn5h1vsn010001pv1cjg2n4t",
      "model": "bass",
      "cost": 4,
      "formats": ["wav"],
      "status": "completed",
      "duration": 200.53,
      "output": [
        {
          "name": "bass",
          "format": "wav",
          "link": "https://cdn.audioshake.ai/..."
        }
      ]
    },
    {
      "id": "cmn5h1vsn00zz01pv6xjn3hxd",
      "model": "drums",
      "formats": ["wav"],
      "status": "processing",
      "output": []
    }
  ]
}

Task-level fields

Field	Always present	Description
`id`	Yes	Unique Task identifier
`createdAt`	Yes	When the Task was created
`completedAt`	No	When all targets finished. `null` while any target is still processing.
`clientId`	Yes	Your client identifier
`assetId`	Yes*	Asset ID of the input file. Absent if `url` was used.
`url`	Yes*	Input URL. Absent if `assetId` was used.
`cost`	No	Total credits consumed across all completed targets. Only present once targets complete.
`metadata`	No	Only present if provided in the original request.

Target fields

Field	Always present	Description
`id`	Yes	Unique target identifier
`model`	Yes	Model that was run
`status`	Yes	`processing`, `completed`, or `error`
`formats`	Yes	Requested output formats
`output`	Yes	Array of downloadable files. Empty `[]` while processing.
`cost`	No	Credits consumed. Only present when `completed`.
`duration`	No	Audio duration processed (seconds). Only present when `completed`.
`error`	No	Error object with `code` and `message`. Only present when `error`.

Output file fields

Field	Description
`name`	Output filename
`format`	File format (e.g. `wav`, `json`)
`link`	Presigned download URL (expires after 1 hour)

Delivery

Sent as POST with Content-Type: application/json
Your endpoint must return a 2xx status code promptly
Output download links expire after one hour — re-fetch the Task for fresh links if needed

API Overview

Assets

Tasks

Setup

Per-Task webhook example

When webhooks fire

Target status reference

Payload

Task-level fields

Target fields

Output file fields

Delivery

​Setup

​Per-Task webhook example

​When webhooks fire

​Target status reference

​Payload

​Task-level fields

​Target fields

​Output file fields

​Delivery

Setup

Per-Task webhook example

When webhooks fire

Target status reference

Payload

Task-level fields

Target fields

Output file fields

Delivery