Webhooks

Webhooks allow you to receive asynchronous notifications when your AI generation tasks are completed. Instead of polling the API for results, you can specify a webhook URL that will receive a POST request with the generation results.

Using Webhooks

To use webhooks, simply add the webhook parameter to your API request URL. The webhook URL should be a publicly accessible HTTPS endpoint that can receive POST requests.

Request Format

When using webhooks, the request format remains the same as the standard API, with the webhook URL specified as a query parameter.

curl --location --request POST 'https://api.wavespeed.ai/api/v2/wavespeed-ai/flux-dev-lora?webhook=https://your.app.user/endpoints' \
--header 'Content-Type: application/json'  \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data-raw '{
    "enable_safety_checker": true,
    "guidance_scale": 5,
    "image": "",
    "loras": [
        {
            "path": "linoyts/yarn_art_Flux_LoRA",
            "scale": 1
        }
    ],
    "num_images": 1,
    "num_inference_steps": 28,
    "prompt": "Octopus vs. crab chess game, underwater setting, vibrant colors",
    "seed": -1,
    "size": "1024*1024",
    "strength": 0.6
}'

Webhook Response

Your webhook endpoint will receive notifications for both successful and failed tasks. The status field in the response will indicate the task outcome:

• completed: Task completed successfully
• failed: Task failed due to an error (check the error field for details)

When your webhook endpoint is called, you’ll receive a POST request with the following structure:

{
    "id": "<task_id>",
    "model": "wavespeed-ai/flux-dev-lora",
    "input": {
        "enable_safety_checker": true,
        "guidance_scale": 5,
        "image": "",
        "loras": [
            {
                "path": "linoyts/yarn_art_Flux_LoRA",
                "scale": 1
            }
        ],
        "num_images": 1,
        "num_inference_steps": 28,
        "prompt": "Octopus vs. crab chess game, underwater setting, vibrant colors",
        "seed": -1,
        "size": "1024*1024",
        "strength": 0.6
    },
    "outputs": [
        "<output_url>"    // Only present when status is "completed"
    ],
    "urls": {
        "get": "https://api.wavespeed.ai/api/v2/predictions/<task_id>/result"
    },
    "has_nsfw_contents": [
        false
    ],
    "status": "completed",  // or "failed"
    "created_at": "<created_at>",
    "error": "<error>",     // Contains error details when status is "failed"
    "executionTime": <execution_time>
}

Best Practices

1. Secure Endpoints: Ensure your webhook endpoint is secured with HTTPS
2. Implement Retry Logic: Your endpoint should be able to handle temporary failures
3. Verify Requests: Implement proper authentication for your webhook endpoint
4. Quick Response: Your webhook handler should respond quickly with a 2xx status code
5. Handle Duplicates: Implement idempotency to handle potential duplicate webhook deliveries

Error Handling

If your webhook endpoint is unavailable or returns an error, we will retry the webhook delivery up to 3 times with exponential backoff. Make sure your endpoint is reliable and can handle the expected load.