## Using Webhooks

Instead of polling for job status, provide a `callback_url` when starting a generation to receive a webhook notification when the job completes or fails.

Include the `callback_url` parameter in your generation request:

### cURL

```
curl -X POST https://api.beeble.ai/v1/switchx/generations \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{\n    "generation_type": "video",\n    "source_uri": "beeble://uploads/upload_xxx/source.mp4",\n    "reference_image_uri": "https://example.com/ref.png",\n    "alpha_mode": "auto",\n    "callback_url": "https://your-server.com/webhook"\n  }'
```

### Python

```
import requests

response = requests.post(
    "https://api.beeble.ai/v1/switchx/generations",
    headers={
        "x-api-key": "YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "generation_type": "video",
        "source_uri": "beeble://uploads/upload_xxx/source.mp4",
        "reference_image_uri": "https://example.com/ref.png",
        "alpha_mode": "auto",
        "callback_url": "https://your-server.com/webhook",
    }
)
```

### JavaScript

```
const response = await fetch("https://api.beeble.ai/v1/switchx/generations", {
    method: "POST",
    headers: {
        "x-api-key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    body: JSON.stringify({
        generation_type: "video",
        source_uri: "beeble://uploads/upload_xxx/source.mp4",
        reference_image_uri: "https://example.com/ref.png",
        alpha_mode: "auto",
        callback_url: "https://your-server.com/webhook",
    }),
});
```

## Webhook Payload

When the job completes or fails, a `POST` request will be sent to your `callback_url`.

**Success:**

```
{
    "id": "swx_abc123",
    "status": "completed",
    "output": {
        "render": "https://cdn.beeble.ai/.../render.mp4",
        "source": "https://cdn.beeble.ai/.../source.mp4",
        "alpha": "https://cdn.beeble.ai/.../alpha.mp4"
    },
    "completed_at": "2026-02-23T10:05:00Z"
}
```

**Failure:**

```
{
    "id": "swx_abc123",
    "status": "failed",
    "completed_at": "2026-02-23T10:05:00Z",
    "error": "Processing failed"
}
```

## Retry Behavior

If your endpoint does not return a `2xx` status code, the webhook will be retried with exponential backoff:

| Attempt | Delay after previous |
| --- | --- |
| 1 | Immediate |
| 2 | ~1 second |
| 3 | ~5 seconds |
| 4 | ~30 seconds |
| 5 | ~2 minutes |

After 5 failed attempts, the webhook is marked as failed. You can check delivery status via the Get Generation Status endpoint:

```
{
  "id": "swx_abc123",
  "status": "completed",
  "webhook": {
    "status": "failed",
    "attempts": 5,
    "last_error": "HTTP 502 Bad Gateway"
  }
}
```

The `webhook` field is only present when a `callback_url` was provided. Possible statuses: `pending`, `delivered`, `failed`.

Your webhook endpoint should return a `2xx` status code within **10 seconds** to acknowledge receipt. Process the payload asynchronously if your handler needs more time.