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

# Webhooks

> Receive notifications when jobs complete or fail

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.

## Using Webhooks

Include the `callback_url` parameter in your generation request:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.beeble.ai/v1/switchx/generations \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "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"
    }'
  ```

  ```python Python theme={null}
  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 JavaScript theme={null}
  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",
      }),
  });
  ```
</CodeGroup>

## Webhook Payload

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

**Success:**

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

```json theme={null}
{
    "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](/docs/api-reference/switchx/get-generation-status) endpoint:

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

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