How to Use Webhooks

Receive automatic notifications when your AI generation tasks complete — no polling required.

What is a Webhook?

A webhook is a URL on your server that receives automatic notifications. Instead of repeatedly asking “Is my task done yet?” (polling), WaveSpeedAI sends the result directly to your server when ready.

Why Use Webhooks?

Benefits of webhooks:

• No wasted API calls checking status
• Instant notification when task completes
• Better for handling many concurrent tasks
• Required for some asynchronous/background job architectures

How It Works

1. You submit a task with a webhook URL parameter
2. WaveSpeedAI processes your task
3. When complete (or failed), WaveSpeedAI POSTs the result to your URL
4. Your server receives and processes the data

Using Webhooks

Add the webhook query parameter to your API request URL. The webhook URL must be a publicly accessible HTTPS endpoint that can receive POST requests.

curl --fail-with-body --connect-timeout 10 --max-time 60 --request POST 'https://api.wavespeed.ai/api/v3/wavespeed-ai/z-image/turbo?webhook=https://your.app.user/endpoints' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer ${WAVESPEED_API_KEY}" \
--data-raw '{
"prompt": "Octopus vs. crab chess game, underwater setting, vibrant colors",
"size": "1024*1024"
}'
  

Webhook Response

When your task completes, we send a POST request to your webhook URL with the following JSON structure:

{
    "id": "<task_id>",
    "model": "wavespeed-ai/z-image/turbo",
    "input": {
        "prompt": "Octopus vs. crab chess game, underwater setting, vibrant colors",
        "size": "1024*1024"
    },
    "outputs": [
        "<output_url>"    // Only present when status is "completed"
    ],
    "urls": {
        "get": "https://api.wavespeed.ai/api/v3/predictions/<task_id>/result"
    },
    "status": "completed",  // or "failed"
    "created_at": "<created_at>",
    "error": "<error>"      // Contains error details when status is "failed"
}

Status Values

Webhook Requirements

Your webhook endpoint must meet these requirements:

Retry & Failure Policy

If your webhook endpoint is unavailable or returns an error:

• Retry attempts: Up to 3 retries when delivery fails
• After all retries fail: The callback is no longer delivered automatically
• Prediction status: Webhook delivery does not change the prediction result or status

Tip: Return 2xx immediately and process the payload asynchronously. If a callback is missed, retrieve the prediction with the result endpoint. A webhook delivery failure does not itself trigger an inference refund.

Limitations

Base64 output is not supported with webhooks

Webhook payloads always contain CDN URLs in the output field — they are not converted to base64 in the callback payload.

If you need base64 output for an async task, poll GET /api/v3/predictions/:id/result instead. See Base64 Output for the polling pattern and decode examples.

Best Practices

1. Verify webhook signatures — Authenticate incoming requests to prevent spoofing. See Verifying Webhooks for implementation details.

2. Respond quickly — Return a 2xx response as soon as you receive the request. Process the data asynchronously if needed.

3. Handle duplicates — Implement idempotency using the id field to handle potential duplicate deliveries.

4. Log everything — Store the raw webhook payload for debugging and auditing.

5. Use queues — For high-volume workloads, push webhook data to a message queue and process separately.

Security

⚠️ Important: Always verify webhook signatures to ensure requests are from WaveSpeedAI.

Webhook endpoints are publicly accessible, meaning anyone could send fake requests. Without verification, malicious actors could:

• Trigger unintended actions in your system
• Inject false data
• Replay old requests

→ Learn how to verify webhook signatures

Troubleshooting

Next Steps

• Verify Webhook Signatures — Secure your webhook endpoint
• Model Library — Explore available models and endpoints

For questions or issues, contact support@wavespeed.ai.