feat: Add webhook support for task completion notifications

README.md

@@ -70,6 +70,7 @@ const output = await wavespeed.run(
     timeout: 36000.0,       // Max wait time in seconds (default: 36000.0)
     pollInterval: 1.0,      // Status check interval (default: 1.0)
     enableSyncMode: false,  // Single request mode, no polling (default: false)
+    webhookUrl: undefined,  // Webhook URL to receive task completion notifications (optional)
   }
 );
 ```
@@ -102,6 +103,22 @@ const client = new Client("your-api-key", {
 });
 ```
 
+### Webhooks
+
+Receive automatic notifications when your AI generation tasks complete — no polling required.
+
+```javascript
+const output = await wavespeed.run(
+  "wavespeed-ai/z-image/turbo",
+  { prompt: "Cat" },
+  {
+    webhookUrl: "https://your.app.user/endpoints"
+  }
+);
+```
+
+> **Note:** Your webhook endpoint must be publicly accessible via HTTPS and respond within 20 minutes. See the [webhook documentation](https://wavespeed.ai/docs/how-to-use-webhooks) for more details.
+
 ### Upload Files
 
 Upload images, videos, or audio files:

src/api/client.ts

@@ -12,6 +12,7 @@ export interface RunOptions {
   pollInterval?: number;      // Interval between status checks in seconds
   enableSyncMode?: boolean;   // If true, use synchronous mode (single request)
   maxRetries?: number;        // Maximum task-level retries (overrides client setting)
+  webhookUrl?: string;        // Webhook URL to receive task completion notifications
 }
 
 /**
@@ -106,6 +107,7 @@ export class Client {
    *     input: Input parameters.
    *     enableSyncMode: If true, wait for result in single request.
    *     timeout: Request timeout in seconds.
+   *     webhookUrl: Webhook URL to receive task completion notifications.
    *
    * Returns:
    *     Tuple of [requestId, result]. In async mode, result is null.
@@ -118,9 +120,18 @@ export class Client {
     model: string,
     input?: Record<string, any>,
     enableSyncMode: boolean = false,
-    timeout?: number
+    timeout?: number,
+    webhookUrl?: string
   ): Promise<[string | null, Record<string, any> | null]> {
-    const url = `${this.baseUrl}/api/v3/${model}`;
+    let url = `${this.baseUrl}/api/v3/${model}`;
+
+    // Add webhook as query parameter if provided
+    if (webhookUrl) {
+      const urlObj = new URL(url);
+      urlObj.searchParams.set('webhook', webhookUrl);
+      url = urlObj.toString();
+    }
+
     const body = input ? { ...input } : {};
 
     if (enableSyncMode) {
@@ -362,6 +373,7 @@ export class Client {
    *     options.pollInterval: Interval between status checks in seconds.
    *     options.enableSyncMode: If true, use synchronous mode (single request).
    *     options.maxRetries: Maximum task-level retries (overrides client setting).
+   *     options.webhookUrl: Webhook URL to receive task completion notifications.
    *
    * Returns:
    *     Dict containing "outputs" array with model outputs.
@@ -380,6 +392,7 @@ export class Client {
     const timeout = options?.timeout ?? this.timeout;
     const pollInterval = options?.pollInterval ?? 1.0;
     const enableSyncMode = options?.enableSyncMode ?? false;
+    const webhookUrl = options?.webhookUrl;
     let lastError: Error | undefined;
 
     for (let attempt = 0; attempt <= taskRetries; attempt++) {
@@ -388,7 +401,8 @@ export class Client {
           model,
           input,
           enableSyncMode,
-          timeout
+          timeout,
+          webhookUrl
         );
 
         if (enableSyncMode) {

src/api/index.ts

@@ -47,6 +47,7 @@ function _getDefaultClient(): Client {
  *     options.pollInterval: Interval between status checks in seconds.
  *     options.enableSyncMode: If true, use synchronous mode (single request).
  *     options.maxRetries: Maximum retries for this request (overrides default setting).
+ *     options.webhookUrl: Webhook URL to receive task completion notifications.
  *
  * Returns:
  *     Dict containing "outputs" array with model outputs.
@@ -76,6 +77,13 @@ function _getDefaultClient(): Client {
  *         { prompt: "A cat" },
  *         { maxRetries: 3 }
  *     );
+ *
+ *     // With webhook
+ *     const output4 = await run(
+ *         "wavespeed-ai/z-image/turbo",
+ *         { prompt: "A cat" },
+ *         { webhookUrl: "https://your.app.user/endpoints" }
+ *     );
  */
 export async function run(
   model: string,