From 1e42c428dfbfa1b109dd9bbd7347258895ff7d62 Mon Sep 17 00:00:00 2001 From: crapthings Date: Mon, 26 Jan 2026 13:20:12 +0800 Subject: [PATCH 1/2] feat: Add webhook support for task completion notifications - Introduced `webhookUrl` option in `RunOptions` interface to allow users to specify a webhook URL for receiving task completion notifications. - Updated documentation and examples in `index.ts` to reflect the new feature. - Modified the `Client` class to handle the `webhookUrl` parameter and append it as a query parameter in API requests. --- src/api/client.ts | 20 +++++++++++++++++--- src/api/index.ts | 8 ++++++++ 2 files changed, 25 insertions(+), 3 deletions(-) diff --git a/src/api/client.ts b/src/api/client.ts index 23f9d75..bb9dd89 100644 --- a/src/api/client.ts +++ b/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, enableSyncMode: boolean = false, - timeout?: number + timeout?: number, + webhookUrl?: string ): Promise<[string | null, Record | 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) { diff --git a/src/api/index.ts b/src/api/index.ts index 2ed2f0d..c7434fa 100644 --- a/src/api/index.ts +++ b/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, From 24a9de34c80c7aed6ad6ce2d6b6cad97e5a2bece Mon Sep 17 00:00:00 2001 From: crapthings Date: Mon, 26 Jan 2026 13:24:55 +0800 Subject: [PATCH 2/2] docs: Update README to include webhook usage examples - Added a section on webhooks for task completion notifications. - Included example code demonstrating how to use the `webhookUrl` option in the `wavespeed.run` method. - Provided a note on the requirements for the webhook endpoint. --- README.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/README.md b/README.md index 86138af..2cb8909 100644 --- a/README.md +++ b/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: