Skip to main content
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"
  }'

​
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:
AttemptDelay after previous
1Immediate
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.