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.

Using Webhooks

Include the callback_url parameter in your generation request:

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"
  }'

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",
    }
)

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.

Get Started

Uploads

SwitchX

Account

Resources

Using Webhooks

Webhook Payload

Retry Behavior

​Using Webhooks

​Webhook Payload

​Retry Behavior

Using Webhooks

Webhook Payload

Retry Behavior