Webhooks - Beeble API Documentation

Using Webhooks

Set callback_url at the top level of a submission request. Use a public HTTPS endpoint that accepts JSON POST requests.

{
  "callback_url": "https://your-server.example/beeble/webhook"
}

Add this field to your job request.

Product job callbacks

data contains the job result. This example shows a failed job:

{
  "event_id": "dap_example",
  "type": "product.job.completed",
  "data": {
    "id": "dap_example",
    "product": "switchx",
    "model_id": "switchx-2.0",
    "organization_id": "org_example",
    "team_id": null,
    "billing_unit": "credits",
    "status": "failed",
    "progress": null,
    "credits_charged": null,
    "refunded": null,
    "outputs": {},
    "error": null,
    "created_at": "2026-09-15T00:00:00Z"
  }
}

Check data.status: the event name indicates the job finished, not that it succeeded. Only success includes output files. Delivery may repeat. Retryable failures get up to ten attempts; permanent failures stop immediately. Redirects are not followed. Revoking the key or removing its organization/team access stops delivery.

Handling Webhooks

Persist the event and return a successful 2xx response within 10 seconds. Do longer work asynchronously.
Deduplicate by event_id, which is the public job ID.
Validate the payload and confirm the job using your authenticated Beeble API connection before taking sensitive actions. A received JSON body alone is not proof of its sender.
Do not interpret a failed job or failure callback as confirmation of a refund. Read the fields described in Billing & credits.