Webhooks - AudioShake Developers

Documentation Index

Fetch the complete documentation index at: /llms.txt

Use this file to discover all available pages before exploring further.

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:

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