Webhooks - Beeble API Documentation

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:

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.