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 serverless/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 --location --request POST 'https://api.wavespeed.ai/api/v3/wavespeed-ai/flux-dev-lora?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"
}'
  

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/flux-dev-lora",
    "input": {
        "prompt": "Octopus vs. crab chess game, underwater setting, vibrant colors"
    },
    "outputs": [
        "<output_url>"    // Only present when status is "completed"
    ],
    "urls": {
        "get": "https://api.wavespeed.ai/api/v3/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"
}

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 times with exponential backoff
• After all retries fail: Task is marked as failed
• Automatic refund: Credits are refunded within 3 hours for webhook delivery failures

Tip: Ensure your endpoint is reliable. Temporary downtime can result in missed notifications and automatic refunds.

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.