feat(api): webhook and deep research support

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 111
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai%2Fopenai-ef4ecb19eb61e24c49d77fef769ee243e5279bc0bdbaee8d0f8dba4da8722559.yml
-openapi_spec_hash: 1b8a9767c9f04e6865b06c41948cdc24
-config_hash: cae2d1f187b5b9f8dfa00daa807da42a
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai%2Fopenai-cca460eaf5cc13e9d6e5293eb97aac53d66dc1385c691f74b768c97d165b6e8b.yml
+openapi_spec_hash: 9ec43d443b3dd58ca5aa87eb0a7eb49f
+config_hash: e74d6791681e3af1b548748ff47a22c2

README.md

@@ -124,6 +124,83 @@ await client.files.create({
 });
 ```
 
+## Webhook Verification
+
+Verifying webhook signatures is _optional but encouraged_.
+
+### Parsing webhook payloads
+
+For most use cases, you will likely want to verify the webhook and parse the payload at the same time. To achieve this, we provide the method `client.webhooks.unwrap()`, which parses a webhook request and verifies that it was sent by OpenAI. This method will throw an error if the signature is invalid.
+
+Note that the `body` parameter must be the raw JSON string sent from the server (do not parse it first). The `.unwrap()` method will parse this JSON for you into an event object after verifying the webhook was sent from OpenAI.
+
+```ts
+import { headers } from 'next/headers';
+import OpenAI from 'openai';
+
+const client = new OpenAI({
+  webhookSecret: process.env.OPENAI_WEBHOOK_SECRET, // env var used by default; explicit here.
+});
+
+export async function webhook(request: Request) {
+  const headersList = headers();
+  const body = await request.text();
+
+  try {
+    const event = client.webhooks.unwrap(body, headersList);
+
+    switch (event.type) {
+      case 'response.completed':
+        console.log('Response completed:', event.data);
+        break;
+      case 'response.failed':
+        console.log('Response failed:', event.data);
+        break;
+      default:
+        console.log('Unhandled event type:', event.type);
+    }
+
+    return Response.json({ message: 'ok' });
+  } catch (error) {
+    console.error('Invalid webhook signature:', error);
+    return new Response('Invalid signature', { status: 400 });
+  }
+}
+```
+
+### Verifying webhook payloads directly
+
+In some cases, you may want to verify the webhook separately from parsing the payload. If you prefer to handle these steps separately, we provide the method `client.webhooks.verifySignature()` to _only verify_ the signature of a webhook request. Like `.unwrap()`, this method will throw an error if the signature is invalid.
+
+Note that the `body` parameter must be the raw JSON string sent from the server (do not parse it first). You will then need to parse the body after verifying the signature.
+
+```ts
+import { headers } from 'next/headers';
+import OpenAI from 'openai';
+
+const client = new OpenAI({
+  webhookSecret: process.env.OPENAI_WEBHOOK_SECRET, // env var used by default; explicit here.
+});
+
+export async function webhook(request: Request) {
+  const headersList = headers();
+  const body = await request.text();
+
+  try {
+    client.webhooks.verifySignature(body, headersList);
+
+    // Parse the body after verification
+    const event = JSON.parse(body);
+    console.log('Verified event:', event);
+
+    return Response.json({ message: 'ok' });
+  } catch (error) {
+    console.error('Invalid webhook signature:', error);
+    return new Response('Invalid signature', { status: 400 });
+  }
+}
+```
+
 ## Handling errors
 
 When the library is unable to connect to the API,

api.md

@@ -351,6 +351,31 @@ Methods:
 - <code>client.vectorStores.files.<a href="./src/resources/vector-stores/files.ts">upload</a>(vectorStoreId, file, options?) -> Promise&lt;VectorStoreFile&gt;</code>
 - <code>client.vectorStores.files.<a href="./src/resources/vector-stores/files.ts">uploadAndPoll</a>(vectorStoreId, file, options?) -> Promise&lt;VectorStoreFile&gt;</code>
 
+# Webhooks
+
+Types:
+
+- <code><a href="./src/resources/webhooks.ts">BatchCancelledWebhookEvent</a></code>
+- <code><a href="./src/resources/webhooks.ts">BatchCompletedWebhookEvent</a></code>
+- <code><a href="./src/resources/webhooks.ts">BatchExpiredWebhookEvent</a></code>
+- <code><a href="./src/resources/webhooks.ts">BatchFailedWebhookEvent</a></code>
+- <code><a href="./src/resources/webhooks.ts">EvalRunCanceledWebhookEvent</a></code>
+- <code><a href="./src/resources/webhooks.ts">EvalRunFailedWebhookEvent</a></code>
+- <code><a href="./src/resources/webhooks.ts">EvalRunSucceededWebhookEvent</a></code>
+- <code><a href="./src/resources/webhooks.ts">FineTuningJobCancelledWebhookEvent</a></code>
+- <code><a href="./src/resources/webhooks.ts">FineTuningJobFailedWebhookEvent</a></code>
+- <code><a href="./src/resources/webhooks.ts">FineTuningJobSucceededWebhookEvent</a></code>
+- <code><a href="./src/resources/webhooks.ts">ResponseCancelledWebhookEvent</a></code>
+- <code><a href="./src/resources/webhooks.ts">ResponseCompletedWebhookEvent</a></code>
+- <code><a href="./src/resources/webhooks.ts">ResponseFailedWebhookEvent</a></code>
+- <code><a href="./src/resources/webhooks.ts">ResponseIncompleteWebhookEvent</a></code>
+- <code><a href="./src/resources/webhooks.ts">UnwrapWebhookEvent</a></code>
+
+Methods:
+
+- <code>client.webhooks.<a href="./src/resources/webhooks.ts">unwrap</a>(payload, headers, secret?, tolerance?) -> UnwrapWebhookEvent</code>
+- <code>client.webhooks.<a href="./src/resources/webhooks.ts">verifySignature</a>(payload, headers, secret?, tolerance?) -> void</code>
+
 # Beta
 
 ## Realtime
@@ -701,6 +726,7 @@ Types:
 - <code><a href="./src/resources/responses/responses.ts">ResponseWebSearchCallSearchingEvent</a></code>
 - <code><a href="./src/resources/responses/responses.ts">Tool</a></code>
 - <code><a href="./src/resources/responses/responses.ts">ToolChoiceFunction</a></code>
+- <code><a href="./src/resources/responses/responses.ts">ToolChoiceMcp</a></code>
 - <code><a href="./src/resources/responses/responses.ts">ToolChoiceOptions</a></code>
 - <code><a href="./src/resources/responses/responses.ts">ToolChoiceTypes</a></code>
 - <code><a href="./src/resources/responses/responses.ts">WebSearchTool</a></code>

src/client.ts

@@ -74,6 +74,7 @@ import {
   ModerationTextInput,
   Moderations,
 } from './resources/moderations';
+import { Webhooks } from './resources/webhooks';
 import { Audio, AudioModel, AudioResponseFormat } from './resources/audio/audio';
 import { Beta } from './resources/beta/beta';
 import { Chat } from './resources/chat/chat';
@@ -196,6 +197,11 @@ export interface ClientOptions {
    */
   project?: string | null | undefined;
 
+  /**
+   * Defaults to process.env['OPENAI_WEBHOOK_SECRET'].
+   */
+  webhookSecret?: string | null | undefined;
+
   /**
    * Override the default base URL for the API, e.g., "https://api.example.com/v2/"
    *
@@ -276,6 +282,7 @@ export class OpenAI {
   apiKey: string;
   organization: string | null;
   project: string | null;
+  webhookSecret: string | null;
 
   baseURL: string;
   maxRetries: number;
@@ -295,6 +302,7 @@ export class OpenAI {
    * @param {string | undefined} [opts.apiKey=process.env['OPENAI_API_KEY'] ?? undefined]
    * @param {string | null | undefined} [opts.organization=process.env['OPENAI_ORG_ID'] ?? null]
    * @param {string | null | undefined} [opts.project=process.env['OPENAI_PROJECT_ID'] ?? null]
+   * @param {string | null | undefined} [opts.webhookSecret=process.env['OPENAI_WEBHOOK_SECRET'] ?? null]
    * @param {string} [opts.baseURL=process.env['OPENAI_BASE_URL'] ?? https://api.openai.com/v1] - Override the default base URL for the API.
    * @param {number} [opts.timeout=10 minutes] - The maximum amount of time (in milliseconds) the client will wait for a response before timing out.
    * @param {MergedRequestInit} [opts.fetchOptions] - Additional `RequestInit` options to be passed to `fetch` calls.
@@ -309,6 +317,7 @@ export class OpenAI {
     apiKey = readEnv('OPENAI_API_KEY'),
     organization = readEnv('OPENAI_ORG_ID') ?? null,
     project = readEnv('OPENAI_PROJECT_ID') ?? null,
+    webhookSecret = readEnv('OPENAI_WEBHOOK_SECRET') ?? null,
     ...opts
   }: ClientOptions = {}) {
     if (apiKey === undefined) {
@@ -321,6 +330,7 @@ export class OpenAI {
       apiKey,
       organization,
       project,
+      webhookSecret,
       ...opts,
       baseURL: baseURL || `https://api.openai.com/v1`,
     };
@@ -351,6 +361,7 @@ export class OpenAI {
     this.apiKey = apiKey;
     this.organization = organization;
     this.project = project;
+    this.webhookSecret = webhookSecret;
   }
 
   /**
@@ -369,6 +380,7 @@ export class OpenAI {
       apiKey: this.apiKey,
       organization: this.organization,
       project: this.project,
+      webhookSecret: this.webhookSecret,
       ...options,
     });
   }
@@ -900,6 +912,7 @@ export class OpenAI {
   static InternalServerError = Errors.InternalServerError;
   static PermissionDeniedError = Errors.PermissionDeniedError;
   static UnprocessableEntityError = Errors.UnprocessableEntityError;
+  static InvalidWebhookSignatureError = Errors.InvalidWebhookSignatureError;
 
   static toFile = Uploads.toFile;
 
@@ -914,6 +927,7 @@ export class OpenAI {
   fineTuning: API.FineTuning = new API.FineTuning(this);
   graders: API.Graders = new API.Graders(this);
   vectorStores: API.VectorStores = new API.VectorStores(this);
+  webhooks: API.Webhooks = new API.Webhooks(this);
   beta: API.Beta = new API.Beta(this);
   batches: API.Batches = new API.Batches(this);
   uploads: API.Uploads = new API.Uploads(this);
@@ -932,6 +946,7 @@ OpenAI.Models = Models;
 OpenAI.FineTuning = FineTuning;
 OpenAI.Graders = Graders;
 OpenAI.VectorStores = VectorStores;
+OpenAI.Webhooks = Webhooks;
 OpenAI.Beta = Beta;
 OpenAI.Batches = Batches;
 OpenAI.Uploads = UploadsAPIUploads;
@@ -1070,6 +1085,8 @@ export declare namespace OpenAI {
     type VectorStoreSearchParams as VectorStoreSearchParams,
   };
 
+  export { Webhooks as Webhooks };
+
   export { Beta as Beta };
 
   export {

src/core/error.ts

@@ -152,3 +152,9 @@ export class ContentFilterFinishReasonError extends OpenAIError {
     super(`Could not parse response content as the request was rejected by the content filter`);
   }
 }
+
+export class InvalidWebhookSignatureError extends Error {
+  constructor(message: string) {
+    super(message);
+  }
+}

src/index.ts

@@ -20,6 +20,7 @@ export {
   InternalServerError,
   PermissionDeniedError,
   UnprocessableEntityError,
+  InvalidWebhookSignatureError,
 } from './core/error';
 
 export { AzureOpenAI } from './azure';

src/resources/chat/completions/completions.ts

@@ -273,25 +273,25 @@ export interface ChatCompletion {
   object: 'chat.completion';
 
   /**
-   * Specifies the latency tier to use for processing the request. This parameter is
-   * relevant for customers subscribed to the scale tier service:
+   * Specifies the processing type used for serving the request.
    *
-   * - If set to 'auto', and the Project is Scale tier enabled, the system will
-   *   utilize scale tier credits until they are exhausted.
-   * - If set to 'auto', and the Project is not Scale tier enabled, the request will
-   *   be processed using the default service tier with a lower uptime SLA and no
-   *   latency guarantee.
-   * - If set to 'default', the request will be processed using the default service
-   *   tier with a lower uptime SLA and no latency guarantee.
-   * - If set to 'flex', the request will be processed with the Flex Processing
-   *   service tier.
-   *   [Learn more](https://platform.openai.com/docs/guides/flex-processing).
+   * - If set to 'auto', then the request will be processed with the service tier
+   *   configured in the Project settings. Unless otherwise configured, the Project
+   *   will use 'default'.
+   * - If set to 'default', then the requset will be processed with the standard
+   *   pricing and performance for the selected model.
+   * - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or
+   *   'priority', then the request will be processed with the corresponding service
+   *   tier. [Contact sales](https://openai.com/contact-sales) to learn more about
+   *   Priority processing.
    * - When not set, the default behavior is 'auto'.
    *
-   * When this parameter is set, the response body will include the `service_tier`
-   * utilized.
+   * When the `service_tier` parameter is set, the response body will include the
+   * `service_tier` value based on the processing mode actually used to serve the
+   * request. This response value may be different from the value set in the
+   * parameter.
    */
-  service_tier?: 'auto' | 'default' | 'flex' | 'scale' | null;
+  service_tier?: 'auto' | 'default' | 'flex' | 'scale' | 'priority' | null;
 
   /**
    * This fingerprint represents the backend configuration that the model runs with.
@@ -524,25 +524,25 @@ export interface ChatCompletionChunk {
   object: 'chat.completion.chunk';
 
   /**
-   * Specifies the latency tier to use for processing the request. This parameter is
-   * relevant for customers subscribed to the scale tier service:
+   * Specifies the processing type used for serving the request.
    *
-   * - If set to 'auto', and the Project is Scale tier enabled, the system will
-   *   utilize scale tier credits until they are exhausted.
-   * - If set to 'auto', and the Project is not Scale tier enabled, the request will
-   *   be processed using the default service tier with a lower uptime SLA and no
-   *   latency guarantee.
-   * - If set to 'default', the request will be processed using the default service
-   *   tier with a lower uptime SLA and no latency guarantee.
-   * - If set to 'flex', the request will be processed with the Flex Processing
-   *   service tier.
-   *   [Learn more](https://platform.openai.com/docs/guides/flex-processing).
+   * - If set to 'auto', then the request will be processed with the service tier
+   *   configured in the Project settings. Unless otherwise configured, the Project
+   *   will use 'default'.
+   * - If set to 'default', then the requset will be processed with the standard
+   *   pricing and performance for the selected model.
+   * - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or
+   *   'priority', then the request will be processed with the corresponding service
+   *   tier. [Contact sales](https://openai.com/contact-sales) to learn more about
+   *   Priority processing.
    * - When not set, the default behavior is 'auto'.
    *
-   * When this parameter is set, the response body will include the `service_tier`
-   * utilized.
+   * When the `service_tier` parameter is set, the response body will include the
+   * `service_tier` value based on the processing mode actually used to serve the
+   * request. This response value may be different from the value set in the
+   * parameter.
    */
-  service_tier?: 'auto' | 'default' | 'flex' | 'scale' | null;
+  service_tier?: 'auto' | 'default' | 'flex' | 'scale' | 'priority' | null;
 
   /**
    * This fingerprint represents the backend configuration that the model runs with.
@@ -1446,25 +1446,25 @@ export interface ChatCompletionCreateParamsBase {
   seed?: number | null;
 
   /**
-   * Specifies the latency tier to use for processing the request. This parameter is
-   * relevant for customers subscribed to the scale tier service:
+   * Specifies the processing type used for serving the request.
    *
-   * - If set to 'auto', and the Project is Scale tier enabled, the system will
-   *   utilize scale tier credits until they are exhausted.
-   * - If set to 'auto', and the Project is not Scale tier enabled, the request will
-   *   be processed using the default service tier with a lower uptime SLA and no
-   *   latency guarantee.
-   * - If set to 'default', the request will be processed using the default service
-   *   tier with a lower uptime SLA and no latency guarantee.
-   * - If set to 'flex', the request will be processed with the Flex Processing
-   *   service tier.
-   *   [Learn more](https://platform.openai.com/docs/guides/flex-processing).
+   * - If set to 'auto', then the request will be processed with the service tier
+   *   configured in the Project settings. Unless otherwise configured, the Project
+   *   will use 'default'.
+   * - If set to 'default', then the requset will be processed with the standard
+   *   pricing and performance for the selected model.
+   * - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or
+   *   'priority', then the request will be processed with the corresponding service
+   *   tier. [Contact sales](https://openai.com/contact-sales) to learn more about
+   *   Priority processing.
    * - When not set, the default behavior is 'auto'.
    *
-   * When this parameter is set, the response body will include the `service_tier`
-   * utilized.
+   * When the `service_tier` parameter is set, the response body will include the
+   * `service_tier` value based on the processing mode actually used to serve the
+   * request. This response value may be different from the value set in the
+   * parameter.
    */
-  service_tier?: 'auto' | 'default' | 'flex' | 'scale' | null;
+  service_tier?: 'auto' | 'default' | 'flex' | 'scale' | 'priority' | null;
 
   /**
    * Not supported with latest reasoning models `o3` and `o4-mini`.
@@ -1478,6 +1478,8 @@ export interface ChatCompletionCreateParamsBase {
    * Whether or not to store the output of this chat completion request for use in
    * our [model distillation](https://platform.openai.com/docs/guides/distillation)
    * or [evals](https://platform.openai.com/docs/guides/evals) products.
+   *
+   * Supports text and image inputs. Note: image inputs over 10MB will be dropped.
    */
   store?: boolean | null;