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

SwitchX callbacks have up to five attempts. Retryable failures use approximately 1, 2, 5, and 10 minute delays before subsequent attempts, with jitter. Permanent failures stop without using the remaining attempts. 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