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

# Webhooks

## Webhooks

Webhooks are used to receive notifications about events in the Blurb API. These notifications help you track the progress of your renders and batches in real-time.

### Webhook Events

The Blurb API sends webhooks for the following events:

* Render status updates: Sent when the status of a render changes
* Batch completion: Sent when a batch of renders is completed

### Example Webhooks

#### Render Status Updates

As a render progresses, you'll receive status updates with the following states:

1. **Collecting Assets**

```json
{
  "renderId": "render_xxxxxxxxxxxxx1",
  "status": "COLLECTING_ASSETS",
  "message": "Collecting assets for this render",
  "renderUrl": "",
  "batchId": "batch_xxxxxxxxxxxxx1",
  "type": "RENDER",
  "progress": 0,
  "ref": "my-custom-reference"
}
```

2. **Rendering in Progress**

```json
{
  "type": "RENDER",
  "ref": "my-custom-reference",
  "status": "RENDERING",
  "progress": 0,
  "message": "Rendering.",
  "renderId": "render_xxxxxxxxxxxxx1",
  "batchId": "batch_xxxxxxxxxxxxx1",
  "renderUrl": ""
}
```

3. **Render Complete**

```json
{
  "type": "RENDER",
  "ref": "my-custom-reference",
  "status": "COMPLETE",
  "progress": 100,
  "message": "Render completed.",
  "renderId": "render_xxxxxxxxxxxxx1",
  "batchId": "batch_xxxxxxxxxxxxx1",
  "renderUrl": "https://api.blurb.fm/render/xxxxxxxxxxxxx1"
}
```

#### Batch Completion

When all renders in a batch are complete, you'll receive a batch completion webhook:

```json
{
  "type": "BATCH",
  "batchId": "batch_xxxxxxxxxxxxx1",
  "ref": "my-custom-reference",
  "renders": [
    {
      "renderId": "render_xxxxxxxxxxxxx1",
      "status": "COMPLETE",
      "message": "Render completed.",
      "progress": 100,
      "renderUrl": "https://api.blurb.fm/render/xxxxxxxxxxxxx1"
    }
    // Additional renders in the batch...
  ],
  "status": "COMPLETE"
}
```

### Webhook Fields

* `type`: The type of event (`RENDER` or `BATCH`)
* `ref`: Your custom reference ID for the render or batch
* `status`: Current status of the render/batch
* `progress`: Progress percentage (0-100)
* `message`: Human-readable status message
* `renderId`: Unique identifier for the render
* `batchId`: Unique identifier for the batch
* `renderUrl`: URL to access the completed render (only present when status is `COMPLETE`)