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 standard_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 standard_webhook query parameter to your API request URL. The webhook URL must be a publicly accessible HTTPS endpoint that can receive POST requests.

Webhooks requested with standard_webhook are signed according to the Standard Webhooks specification, so you can verify them with an official library. See Verifying Webhooks.

curl --fail-with-body --connect-timeout 10 --max-time 60 --request POST 'https://api.wavespeed.ai/api/v3/wavespeed-ai/z-image/turbo?standard_webhook=https://example.com/webhooks/wavespeed' \
--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 a failure terminal status
    "created_at": "<created_at>",
    "error": "<error>"      // May contain details for a failure terminal status
}

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

Sync mode is not supported with webhooks

Requests that combine a standard_webhook or webhook query parameter with "enable_sync_mode": true are rejected. Webhooks are for asynchronous completion notifications; use sync mode without a webhook when you need the result in the submission response.

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.

Requests that combine a standard_webhook or webhook query parameter with "enable_base64_output": true are rejected. If you need base64 output for an async task, omit the webhook and 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. Keep polling as a fallback — A delivery can still fail, for example when your endpoint is unreachable during every retry. Keep track of the predictions you submit, and if a webhook has not arrived well after a prediction should have finished, fetch it with GET /api/v3/predictions/{id}/result.

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

6. 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.