Webhooks

Instead of polling for results, you can have LEAPERone push a notification to your server when an asynchronous task (such as image generation) finishes.

How It Works

Include a callbackUrl in your request. When the task completes (or fails), LEAPERone sends a JSON POST request to that URL.

Request with callbackUrl

{
  "model": "gpt-4o-image",
  "prompt": "A neon-lit cyberpunk cityscape",
  "callbackUrl": "https://your-server.com/webhook/image"
}

The callbackUrl must use HTTPS and must not point to private or internal network addresses.

Webhook Payload

When the task finishes, LEAPERone sends a POST request with a JSON body:

Completed payload

{
  "id": "img-abc123",
  "status": "completed",
  "images": [
    {
      "id": "img-file-1",
      "url": "https://cdn.leaper.one/images/abc123.png"
    }
  ]
}

Failed payload

{
  "id": "img-abc123",
  "status": "failed",
  "error": "Content policy violation"
}

Payload Fields

Field	Type	Description
`id`	string	The generation task ID.
`status`	string	`completed`, `uploading`, or `failed`.
`images`	array	Present on success. Each entry has `id` and `url`.
`error`	string	Present on failure. Describes what went wrong.

Automatic Retries

If your endpoint returns a non-2xx status code or the request times out (10 seconds), LEAPERone retries up to 5 times with exponential backoff (starting at 2 seconds, capped at 30 seconds).

If all retries are exhausted, the callback is marked as failed. You can still retrieve the result by polling the GET /v1/images/generations/:id endpoint.

Verifying Webhook Source

There is currently no signature header for webhook verification. To protect your endpoint, consider these strategies:

Use a secret path that is hard to guess (e.g., https://your-server.com/webhook/a8f3b2c1).
Verify the id in the payload by calling GET /v1/images/generations/:id to confirm it exists and matches.
Restrict inbound traffic to known IP ranges if your infrastructure supports it.

Best Practices

Respond quickly. Return a 200 status as soon as you receive the payload. Process the data asynchronously on your side to avoid timeouts.
Handle duplicates. In rare cases a retry may arrive after a previous attempt already succeeded. Use the id field to deduplicate.
Download images promptly. Image URLs are temporary and expire after 1 hour.