> ## Documentation Index
> Fetch the complete documentation index at: https://developer.audioshake.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Receive notifications when target status changes

AudioShake sends a `POST` request to your webhook URL each time a [Task's](https://developer.audioshake.ai/api-reference/tasks/create.md) Target changes status. The payload is the full Task object, identical to the response from [Get Task by ID](https://developer.audioshake.ai/api-reference/tasks/get.md).

## Setup

You can configure a webhook URL in two ways:

* **Globally** — set a default webhook URL in the [AudioShake Dashboard](https://dashboard.audioshake.ai) under **Settings > Webhook URL**. It applies to every Task on your account.
* **Per Task** — set `webhookUrl` in the body of your [Create Task](https://developer.audioshake.ai/api-reference/tasks/create.md) request. This applies to that Task only.

> [!NOTE]
>
> 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

```bash theme={null}
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`.

> [!NOTE]
>
> 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`:

```json theme={null}
{
  "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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.