feat(api): webhook and deep research support

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 109
-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

Gemfile.lock

@@ -54,6 +54,7 @@ GEM
     csv (3.3.4)
     drb (2.2.1)
     erubi (1.13.1)
+    ffi (1.17.2-arm64-darwin)
     ffi (1.17.2-x86_64-linux-gnu)
     fiber-annotation (0.2.0)
     fiber-local (1.1.0)
@@ -124,6 +125,7 @@ GEM
     sorbet (0.5.12067)
       sorbet-static (= 0.5.12067)
     sorbet-runtime (0.5.12067)
+    sorbet-static (0.5.12067-universal-darwin)
     sorbet-static (0.5.12067-x86_64-linux)
     sorbet-static-and-runtime (0.5.12067)
       sorbet (= 0.5.12067)
@@ -185,6 +187,7 @@ GEM
       yard
 
 PLATFORMS
+  arm64-darwin-24
   x86_64-linux
 
 DEPENDENCIES

README.md

@@ -112,6 +112,82 @@ puts(edited.data.first)
 
 Note that you can also pass a raw `IO` descriptor, but this disables retries, as the library can't be sure if the descriptor is a file or pipe (which cannot be rewound).
 
+## 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 raise 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.
+
+```ruby
+require 'sinatra'
+require 'openai'
+
+# Set up the client with webhook secret from environment variable
+client = OpenAI::Client.new(webhook_secret: ENV['OPENAI_WEBHOOK_SECRET'])
+
+post '/webhook' do
+  request_body = request.body.read
+  
+  begin
+    event = client.webhooks.unwrap(request_body, request.env)
+    
+    case event.type
+    when 'response.completed'
+      puts "Response completed: #{event.data}"
+    when 'response.failed'
+      puts "Response failed: #{event.data}"
+    else
+      puts "Unhandled event type: #{event.type}"
+    end
+    
+    status 200
+    'ok'
+  rescue StandardError => e
+    puts "Invalid signature: #{e}"
+    status 400
+    'Invalid signature'
+  end
+end
+```
+
+### 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.verify_signature` to _only verify_ the signature of a webhook request. Like `unwrap`, this method will raise 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.
+
+```ruby
+require 'sinatra'
+require 'json'
+require 'openai'
+
+# Set up the client with webhook secret from environment variable
+client = OpenAI::Client.new(webhook_secret: ENV['OPENAI_WEBHOOK_SECRET'])
+
+post '/webhook' do
+  request_body = request.body.read
+  
+  begin
+    client.webhooks.verify_signature(request_body, request.env)
+    
+    # Parse the body after verification
+    event = JSON.parse(request_body)
+    puts "Verified event: #{event}"
+    
+    status 200
+    'ok'
+  rescue StandardError => e
+    puts "Invalid signature: #{e}"
+    status 400
+    'Invalid signature'
+  end
+end
+```
+
 ### [Structured outputs](https://platform.openai.com/docs/guides/structured-outputs) and function calling
 
 This SDK ships with helpers in `OpenAI::BaseModel`, `OpenAI::ArrayOf`, `OpenAI::EnumOf`, and `OpenAI::UnionOf` to help you define the supported JSON schemas used in making structured outputs and function calling requests.

lib/openai.rb

@@ -441,6 +441,7 @@
 require_relative "openai/models/responses/response_web_search_call_searching_event"
 require_relative "openai/models/responses/tool"
 require_relative "openai/models/responses/tool_choice_function"
+require_relative "openai/models/responses/tool_choice_mcp"
 require_relative "openai/models/responses/tool_choice_options"
 require_relative "openai/models/responses/tool_choice_types"
 require_relative "openai/models/responses/web_search_tool"
@@ -477,6 +478,22 @@
 require_relative "openai/models/vector_store_search_params"
 require_relative "openai/models/vector_store_search_response"
 require_relative "openai/models/vector_store_update_params"
+require_relative "openai/models/webhooks/batch_cancelled_webhook_event"
+require_relative "openai/models/webhooks/batch_completed_webhook_event"
+require_relative "openai/models/webhooks/batch_expired_webhook_event"
+require_relative "openai/models/webhooks/batch_failed_webhook_event"
+require_relative "openai/models/webhooks/eval_run_canceled_webhook_event"
+require_relative "openai/models/webhooks/eval_run_failed_webhook_event"
+require_relative "openai/models/webhooks/eval_run_succeeded_webhook_event"
+require_relative "openai/models/webhooks/fine_tuning_job_cancelled_webhook_event"
+require_relative "openai/models/webhooks/fine_tuning_job_failed_webhook_event"
+require_relative "openai/models/webhooks/fine_tuning_job_succeeded_webhook_event"
+require_relative "openai/models/webhooks/response_cancelled_webhook_event"
+require_relative "openai/models/webhooks/response_completed_webhook_event"
+require_relative "openai/models/webhooks/response_failed_webhook_event"
+require_relative "openai/models/webhooks/response_incomplete_webhook_event"
+require_relative "openai/models/webhooks/unwrap_webhook_event"
+require_relative "openai/models/webhooks/webhook_unwrap_params"
 require_relative "openai/models"
 require_relative "openai/resources/audio"
 require_relative "openai/resources/audio/speech"
@@ -521,3 +538,4 @@
 require_relative "openai/resources/vector_stores"
 require_relative "openai/resources/vector_stores/file_batches"
 require_relative "openai/resources/vector_stores/files"
+require_relative "openai/resources/webhooks"

lib/openai/client.rb

@@ -24,6 +24,9 @@ class Client < OpenAI::Internal::Transport::BaseClient
     # @return [String, nil]
     attr_reader :project
 
+    # @return [String, nil]
+    attr_reader :webhook_secret
+
     # @return [OpenAI::Resources::Completions]
     attr_reader :completions
 
@@ -57,6 +60,9 @@ class Client < OpenAI::Internal::Transport::BaseClient
     # @return [OpenAI::Resources::VectorStores]
     attr_reader :vector_stores
 
+    # @return [OpenAI::Resources::Webhooks]
+    attr_reader :webhooks
+
     # @return [OpenAI::Resources::Beta]
     attr_reader :beta
 
@@ -92,6 +98,8 @@ class Client < OpenAI::Internal::Transport::BaseClient
     #
     # @param project [String, nil] Defaults to `ENV["OPENAI_PROJECT_ID"]`
     #
+    # @param webhook_secret [String, nil] Defaults to `ENV["OPENAI_WEBHOOK_SECRET"]`
+    #
     # @param base_url [String, nil] Override the default base URL for the API, e.g.,
     # `"https://api.example.com/v2/"`. Defaults to `ENV["OPENAI_BASE_URL"]`
     #
@@ -106,6 +114,7 @@ def initialize(
       api_key: ENV["OPENAI_API_KEY"],
       organization: ENV["OPENAI_ORG_ID"],
       project: ENV["OPENAI_PROJECT_ID"],
+      webhook_secret: ENV["OPENAI_WEBHOOK_SECRET"],
       base_url: ENV["OPENAI_BASE_URL"],
       max_retries: self.class::DEFAULT_MAX_RETRIES,
       timeout: self.class::DEFAULT_TIMEOUT_IN_SECONDS,
@@ -124,6 +133,7 @@ def initialize(
       }
 
       @api_key = api_key.to_s
+      @webhook_secret = webhook_secret&.to_s
 
       super(
         base_url: base_url,
@@ -145,6 +155,7 @@ def initialize(
       @fine_tuning = OpenAI::Resources::FineTuning.new(client: self)
       @graders = OpenAI::Resources::Graders.new(client: self)
       @vector_stores = OpenAI::Resources::VectorStores.new(client: self)
+      @webhooks = OpenAI::Resources::Webhooks.new(client: self)
       @beta = OpenAI::Resources::Beta.new(client: self)
       @batches = OpenAI::Resources::Batches.new(client: self)
       @uploads = OpenAI::Resources::Uploads.new(client: self)

lib/openai/models.rb

@@ -234,4 +234,6 @@ module OpenAI
   VectorStoreSearchParams = OpenAI::Models::VectorStoreSearchParams
 
   VectorStoreUpdateParams = OpenAI::Models::VectorStoreUpdateParams
+
+  Webhooks = OpenAI::Models::Webhooks
 end

lib/openai/models/all_models.rb

@@ -18,6 +18,10 @@ module ResponsesOnlyModel
         O1_PRO_2025_03_19 = :"o1-pro-2025-03-19"
         O3_PRO = :"o3-pro"
         O3_PRO_2025_06_10 = :"o3-pro-2025-06-10"
+        O3_DEEP_RESEARCH = :"o3-deep-research"
+        O3_DEEP_RESEARCH_2025_06_26 = :"o3-deep-research-2025-06-26"
+        O4_MINI_DEEP_RESEARCH = :"o4-mini-deep-research"
+        O4_MINI_DEEP_RESEARCH_2025_06_26 = :"o4-mini-deep-research-2025-06-26"
         COMPUTER_USE_PREVIEW = :"computer-use-preview"
         COMPUTER_USE_PREVIEW_2025_03_11 = :"computer-use-preview-2025-03-11"
 

lib/openai/models/chat/chat_completion.rb

@@ -39,23 +39,23 @@ class ChatCompletion < OpenAI::Internal::Type::BaseModel
         required :object, const: :"chat.completion"
 
         # @!attribute service_tier
-        #   Specifies the latency tier to use for processing the request. This parameter is
-        #   relevant for customers subscribed to the scale tier service:
-        #
-        #   - 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).
+        #   Specifies the processing type used for serving the request.
+        #
+        #   - 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.
         #
         #   @return [Symbol, OpenAI::Models::Chat::ChatCompletion::ServiceTier, nil]
         optional :service_tier, enum: -> { OpenAI::Chat::ChatCompletion::ServiceTier }, nil?: true
@@ -90,7 +90,7 @@ class ChatCompletion < OpenAI::Internal::Type::BaseModel
         #
         #   @param model [String] The model used for the chat completion.
         #
-        #   @param service_tier [Symbol, OpenAI::Models::Chat::ChatCompletion::ServiceTier, nil] Specifies the latency tier to use for processing the request. This parameter is
+        #   @param service_tier [Symbol, OpenAI::Models::Chat::ChatCompletion::ServiceTier, nil] Specifies the processing type used for serving the request.
         #
         #   @param system_fingerprint [String] This fingerprint represents the backend configuration that the model runs with.
         #
@@ -188,23 +188,23 @@ class Logprobs < OpenAI::Internal::Type::BaseModel
           end
         end
 
-        # Specifies the latency tier to use for processing the request. This parameter is
-        # relevant for customers subscribed to the scale tier service:
-        #
-        # - 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).
+        # Specifies the processing type used for serving the request.
+        #
+        # - 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.
         #
         # @see OpenAI::Models::Chat::ChatCompletion#service_tier
         module ServiceTier
@@ -214,6 +214,7 @@ module ServiceTier
           DEFAULT = :default
           FLEX = :flex
           SCALE = :scale
+          PRIORITY = :priority
 
           # @!method self.values
           #   @return [Array<Symbol>]