> ## 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](/api-reference/tasks/create) Target changes status. The payload is the full Task object, identical to the response from [Get Task by ID](/api-reference/tasks/get).

## 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](/api-reference/tasks/create) request. This applies to that Task only.

<Info>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.</Info>

### 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`.

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

## 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