Merge pull request #429 from openai/release-please--branches--main--changes--next

release: 1.8.0

Author: kwhinnery-openai

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "1.7.0"
+  ".": "1.8.0"
 }

.stats.yml

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

CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 1.8.0 (2025-06-26)
+
+Full Changelog: [v1.7.0...v1.8.0](https://github.com/openai/openai-go/compare/v1.7.0...v1.8.0)
+
+### Features
+
+* **api:** webhook and deep research support ([f6a7e7d](https://github.com/openai/openai-go/commit/f6a7e7dcd8801facc4f8d981f1ca43786c10de1e))
+
+
+### Chores
+
+* **internal:** add tests for breaking change detection ([339522d](https://github.com/openai/openai-go/commit/339522d38cd31b0753a8df37b8924f7e7dfb0b1d))
+
 ## 1.7.0 (2025-06-23)
 
 Full Changelog: [v1.6.0...v1.7.0](https://github.com/openai/openai-go/compare/v1.6.0...v1.7.0)

README.md

@@ -26,7 +26,7 @@ Or to pin the version:
 <!-- x-release-please-start-version -->
 
 ```sh
-go get -u 'github.com/openai/openai-go@v1.7.0'
+go get -u 'github.com/openai/openai-go@v1.8.0'
 ```
 
 <!-- x-release-please-end -->
@@ -630,6 +630,119 @@ openai.FileNewParams{
 }
 ```
 
+## 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 return an error if the signature is invalid.
+
+Note that the `body` parameter should be the raw JSON bytes 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.
+
+```go
+package main
+
+import (
+	"io"
+	"log"
+	"net/http"
+	"os"
+
+	"github.com/gin-gonic/gin"
+	"github.com/openai/openai-go"
+	"github.com/openai/openai-go/option"
+	"github.com/openai/openai-go/webhooks"
+)
+
+func main() {
+	client := openai.NewClient(
+		option.WithWebhookSecret(os.Getenv("OPENAI_WEBHOOK_SECRET")), // env var used by default; explicit here.
+	)
+
+	r := gin.Default()
+	
+	r.POST("/webhook", func(c *gin.Context) {
+		body, err := io.ReadAll(c.Request.Body)
+		if err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": "Error reading request body"})
+			return
+		}
+		defer c.Request.Body.Close()
+
+		webhookEvent, err := client.Webhooks.Unwrap(body, c.Request.Header)
+		if err != nil {
+			log.Printf("Invalid webhook signature: %v", err)
+			c.JSON(http.StatusBadRequest, gin.H{"error": "invalid signature"})
+			return
+		}
+
+		switch event := webhookEvent.AsAny().(type) {
+		case webhooks.ResponseCompletedWebhookEvent:
+			log.Printf("Response completed: %+v", event.Data)
+		case webhooks.ResponseFailedWebhookEvent:
+			log.Printf("Response failed: %+v", event.Data)
+		default:
+			log.Printf("Unhandled event type: %T", event)
+		}
+
+		c.JSON(http.StatusOK, gin.H{"message": "ok"})
+	})
+
+	r.Run(":8000")
+}
+```
+
+### 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 return an error if the signature is invalid.
+
+Note that the `body` parameter should be the raw JSON bytes sent from the server (do not parse it first). You will then need to parse the body after verifying the signature.
+
+```go
+package main
+
+import (
+	"encoding/json"
+	"io"
+	"log"
+	"net/http"
+	"os"
+
+	"github.com/gin-gonic/gin"
+	"github.com/openai/openai-go"
+	"github.com/openai/openai-go/option"
+)
+
+func main() {
+	client := openai.NewClient(
+		option.WithWebhookSecret(os.Getenv("OPENAI_WEBHOOK_SECRET")), // env var used by default; explicit here.
+	)
+
+	r := gin.Default()
+	
+	r.POST("/webhook", func(c *gin.Context) {
+		body, err := io.ReadAll(c.Request.Body)
+		if err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": "Error reading request body"})
+			return
+		}
+		defer c.Request.Body.Close()
+
+		err = client.Webhooks.VerifySignature(body, c.Request.Header)
+		if err != nil {
+			log.Printf("Invalid webhook signature: %v", err)
+			c.JSON(http.StatusBadRequest, gin.H{"error": "invalid signature"})
+			return
+		}
+		
+		c.JSON(http.StatusOK, gin.H{"message": "ok"})
+	})
+
+	r.Run(":8000")
+}
+```
+
 ### Retries
 
 Certain errors will be automatically retried 2 times by default, with a short exponential backoff.

aliases.go

@@ -421,6 +421,18 @@ const ResponsesModelO3Pro = shared.ResponsesModelO3Pro
 // Equals "o3-pro-2025-06-10"
 const ResponsesModelO3Pro2025_06_10 = shared.ResponsesModelO3Pro2025_06_10
 
+// Equals "o3-deep-research"
+const ResponsesModelO3DeepResearch = shared.ResponsesModelO3DeepResearch
+
+// Equals "o3-deep-research-2025-06-26"
+const ResponsesModelO3DeepResearch2025_06_26 = shared.ResponsesModelO3DeepResearch2025_06_26
+
+// Equals "o4-mini-deep-research"
+const ResponsesModelO4MiniDeepResearch = shared.ResponsesModelO4MiniDeepResearch
+
+// Equals "o4-mini-deep-research-2025-06-26"
+const ResponsesModelO4MiniDeepResearch2025_06_26 = shared.ResponsesModelO4MiniDeepResearch2025_06_26
+
 // Equals "computer-use-preview"
 const ResponsesModelComputerUsePreview = shared.ResponsesModelComputerUsePreview
 

api.md

@@ -380,6 +380,35 @@ Methods:
 - <code title="post /vector_stores/{vector_store_id}/file_batches/{batch_id}/cancel">client.VectorStores.FileBatches.<a href="https://pkg.go.dev/github.com/openai/openai-go#VectorStoreFileBatchService.Cancel">Cancel</a>(ctx <a href="https://pkg.go.dev/context">context</a>.<a href="https://pkg.go.dev/context#Context">Context</a>, vectorStoreID <a href="https://pkg.go.dev/builtin#string">string</a>, batchID <a href="https://pkg.go.dev/builtin#string">string</a>) (<a href="https://pkg.go.dev/github.com/openai/openai-go">openai</a>.<a href="https://pkg.go.dev/github.com/openai/openai-go#VectorStoreFileBatch">VectorStoreFileBatch</a>, <a href="https://pkg.go.dev/builtin#error">error</a>)</code>
 - <code title="get /vector_stores/{vector_store_id}/file_batches/{batch_id}/files">client.VectorStores.FileBatches.<a href="https://pkg.go.dev/github.com/openai/openai-go#VectorStoreFileBatchService.ListFiles">ListFiles</a>(ctx <a href="https://pkg.go.dev/context">context</a>.<a href="https://pkg.go.dev/context#Context">Context</a>, vectorStoreID <a href="https://pkg.go.dev/builtin#string">string</a>, batchID <a href="https://pkg.go.dev/builtin#string">string</a>, query <a href="https://pkg.go.dev/github.com/openai/openai-go">openai</a>.<a href="https://pkg.go.dev/github.com/openai/openai-go#VectorStoreFileBatchListFilesParams">VectorStoreFileBatchListFilesParams</a>) (<a href="https://pkg.go.dev/github.com/openai/openai-go/packages/pagination">pagination</a>.<a href="https://pkg.go.dev/github.com/openai/openai-go/packages/pagination#CursorPage">CursorPage</a>[<a href="https://pkg.go.dev/github.com/openai/openai-go">openai</a>.<a href="https://pkg.go.dev/github.com/openai/openai-go#VectorStoreFile">VectorStoreFile</a>], <a href="https://pkg.go.dev/builtin#error">error</a>)</code>
 
+# Webhooks
+
+Response Types:
+
+- <a href="https://pkg.go.dev/github.com/openai/openai-go/webhooks">webhooks</a>.<a href="https://pkg.go.dev/github.com/openai/openai-go/webhooks#BatchCancelledWebhookEvent">BatchCancelledWebhookEvent</a>
+- <a href="https://pkg.go.dev/github.com/openai/openai-go/webhooks">webhooks</a>.<a href="https://pkg.go.dev/github.com/openai/openai-go/webhooks#BatchCompletedWebhookEvent">BatchCompletedWebhookEvent</a>
+- <a href="https://pkg.go.dev/github.com/openai/openai-go/webhooks">webhooks</a>.<a href="https://pkg.go.dev/github.com/openai/openai-go/webhooks#BatchExpiredWebhookEvent">BatchExpiredWebhookEvent</a>
+- <a href="https://pkg.go.dev/github.com/openai/openai-go/webhooks">webhooks</a>.<a href="https://pkg.go.dev/github.com/openai/openai-go/webhooks#BatchFailedWebhookEvent">BatchFailedWebhookEvent</a>
+- <a href="https://pkg.go.dev/github.com/openai/openai-go/webhooks">webhooks</a>.<a href="https://pkg.go.dev/github.com/openai/openai-go/webhooks#EvalRunCanceledWebhookEvent">EvalRunCanceledWebhookEvent</a>
+- <a href="https://pkg.go.dev/github.com/openai/openai-go/webhooks">webhooks</a>.<a href="https://pkg.go.dev/github.com/openai/openai-go/webhooks#EvalRunFailedWebhookEvent">EvalRunFailedWebhookEvent</a>
+- <a href="https://pkg.go.dev/github.com/openai/openai-go/webhooks">webhooks</a>.<a href="https://pkg.go.dev/github.com/openai/openai-go/webhooks#EvalRunSucceededWebhookEvent">EvalRunSucceededWebhookEvent</a>
+- <a href="https://pkg.go.dev/github.com/openai/openai-go/webhooks">webhooks</a>.<a href="https://pkg.go.dev/github.com/openai/openai-go/webhooks#FineTuningJobCancelledWebhookEvent">FineTuningJobCancelledWebhookEvent</a>
+- <a href="https://pkg.go.dev/github.com/openai/openai-go/webhooks">webhooks</a>.<a href="https://pkg.go.dev/github.com/openai/openai-go/webhooks#FineTuningJobFailedWebhookEvent">FineTuningJobFailedWebhookEvent</a>
+- <a href="https://pkg.go.dev/github.com/openai/openai-go/webhooks">webhooks</a>.<a href="https://pkg.go.dev/github.com/openai/openai-go/webhooks#FineTuningJobSucceededWebhookEvent">FineTuningJobSucceededWebhookEvent</a>
+- <a href="https://pkg.go.dev/github.com/openai/openai-go/webhooks">webhooks</a>.<a href="https://pkg.go.dev/github.com/openai/openai-go/webhooks#ResponseCancelledWebhookEvent">ResponseCancelledWebhookEvent</a>
+- <a href="https://pkg.go.dev/github.com/openai/openai-go/webhooks">webhooks</a>.<a href="https://pkg.go.dev/github.com/openai/openai-go/webhooks#ResponseCompletedWebhookEvent">ResponseCompletedWebhookEvent</a>
+- <a href="https://pkg.go.dev/github.com/openai/openai-go/webhooks">webhooks</a>.<a href="https://pkg.go.dev/github.com/openai/openai-go/webhooks#ResponseFailedWebhookEvent">ResponseFailedWebhookEvent</a>
+- <a href="https://pkg.go.dev/github.com/openai/openai-go/webhooks">webhooks</a>.<a href="https://pkg.go.dev/github.com/openai/openai-go/webhooks#ResponseIncompleteWebhookEvent">ResponseIncompleteWebhookEvent</a>
+- <a href="https://pkg.go.dev/github.com/openai/openai-go/webhooks">webhooks</a>.<a href="https://pkg.go.dev/github.com/openai/openai-go/webhooks#UnwrapWebhookEventUnion">UnwrapWebhookEventUnion</a>
+
+Methods:
+
+- <code>client.Webhooks.<a href="https://pkg.go.dev/github.com/openai/openai-go/webhooks#WebhookService.Unwrap">Unwrap</a>(body []<a href="https://pkg.go.dev/builtin#byte">byte</a>, headers <a href="https://pkg.go.dev/net/http">http</a>.<a href="https://pkg.go.dev/net/http#Header">Header</a>, opts ...<a href="https://pkg.go.dev/github.com/openai/openai-go/option">option</a>.<a href="https://pkg.go.dev/github.com/openai/openai-go/option#RequestOption">RequestOption</a>) (*<a href="https://pkg.go.dev/github.com/openai/openai-go/webhooks">webhooks</a>.<a href="https://pkg.go.dev/github.com/openai/openai-go/webhooks#UnwrapWebhookEventUnion">UnwrapWebhookEventUnion</a>, <a href="https://pkg.go.dev/builtin#error">error</a>)</code>
+- <code>client.Webhooks.<a href="https://pkg.go.dev/github.com/openai/openai-go/webhooks#WebhookService.UnwrapWithTolerance">UnwrapWithTolerance</a>(body []<a href="https://pkg.go.dev/builtin#byte">byte</a>, headers <a href="https://pkg.go.dev/net/http">http</a>.<a href="https://pkg.go.dev/net/http#Header">Header</a>, tolerance <a href="https://pkg.go.dev/time">time</a>.<a href="https://pkg.go.dev/time#Duration">Duration</a>, opts ...<a href="https://pkg.go.dev/github.com/openai/openai-go/option">option</a>.<a href="https://pkg.go.dev/github.com/openai/openai-go/option#RequestOption">RequestOption</a>) (*<a href="https://pkg.go.dev/github.com/openai/openai-go/webhooks">webhooks</a>.<a href="https://pkg.go.dev/github.com/openai/openai-go/webhooks#UnwrapWebhookEventUnion">UnwrapWebhookEventUnion</a>, <a href="https://pkg.go.dev/builtin#error">error</a>)</code>
+- <code>client.Webhooks.<a href="https://pkg.go.dev/github.com/openai/openai-go/webhooks#WebhookService.UnwrapWithToleranceAndTime">UnwrapWithToleranceAndTime</a>(body []<a href="https://pkg.go.dev/builtin#byte">byte</a>, headers <a href="https://pkg.go.dev/net/http">http</a>.<a href="https://pkg.go.dev/net/http#Header">Header</a>, tolerance <a href="https://pkg.go.dev/time">time</a>.<a href="https://pkg.go.dev/time#Duration">Duration</a>, now <a href="https://pkg.go.dev/time">time</a>.<a href="https://pkg.go.dev/time#Time">Time</a>, opts ...<a href="https://pkg.go.dev/github.com/openai/openai-go/option">option</a>.<a href="https://pkg.go.dev/github.com/openai/openai-go/option#RequestOption">RequestOption</a>) (*<a href="https://pkg.go.dev/github.com/openai/openai-go/webhooks">webhooks</a>.<a href="https://pkg.go.dev/github.com/openai/openai-go/webhooks#UnwrapWebhookEventUnion">UnwrapWebhookEventUnion</a>, <a href="https://pkg.go.dev/builtin#error">error</a>)</code>
+- <code>client.Webhooks.<a href="https://pkg.go.dev/github.com/openai/openai-go/webhooks#WebhookService.VerifySignature">VerifySignature</a>(body []<a href="https://pkg.go.dev/builtin#byte">byte</a>, headers <a href="https://pkg.go.dev/net/http">http</a>.<a href="https://pkg.go.dev/net/http#Header">Header</a>, opts ...<a href="https://pkg.go.dev/github.com/openai/openai-go/option">option</a>.<a href="https://pkg.go.dev/github.com/openai/openai-go/option#RequestOption">RequestOption</a>) <a href="https://pkg.go.dev/builtin#error">error</a></code>
+- <code>client.Webhooks.<a href="https://pkg.go.dev/github.com/openai/openai-go/webhooks#WebhookService.VerifySignatureWithTolerance">VerifySignatureWithTolerance</a>(body []<a href="https://pkg.go.dev/builtin#byte">byte</a>, headers <a href="https://pkg.go.dev/net/http">http</a>.<a href="https://pkg.go.dev/net/http#Header">Header</a>, tolerance <a href="https://pkg.go.dev/time">time</a>.<a href="https://pkg.go.dev/time#Duration">Duration</a>, opts ...<a href="https://pkg.go.dev/github.com/openai/openai-go/option">option</a>.<a href="https://pkg.go.dev/github.com/openai/openai-go/option#RequestOption">RequestOption</a>) <a href="https://pkg.go.dev/builtin#error">error</a></code>
+- <code>client.Webhooks.<a href="https://pkg.go.dev/github.com/openai/openai-go/webhooks#WebhookService.VerifySignatureWithToleranceAndTime">VerifySignatureWithToleranceAndTime</a>(body []<a href="https://pkg.go.dev/builtin#byte">byte</a>, headers <a href="https://pkg.go.dev/net/http">http</a>.<a href="https://pkg.go.dev/net/http#Header">Header</a>, tolerance <a href="https://pkg.go.dev/time">time</a>.<a href="https://pkg.go.dev/time#Duration">Duration</a>, now <a href="https://pkg.go.dev/time">time</a>.<a href="https://pkg.go.dev/time#Time">Time</a>, opts ...<a href="https://pkg.go.dev/github.com/openai/openai-go/option">option</a>.<a href="https://pkg.go.dev/github.com/openai/openai-go/option#RequestOption">RequestOption</a>) <a href="https://pkg.go.dev/builtin#error">error</a></code>
+
 # Beta
 
 ## Assistants
@@ -600,6 +629,7 @@ Params Types:
 - <a href="https://pkg.go.dev/github.com/openai/openai-go/responses">responses</a>.<a href="https://pkg.go.dev/github.com/openai/openai-go/responses#ResponseTextConfigParam">ResponseTextConfigParam</a>
 - <a href="https://pkg.go.dev/github.com/openai/openai-go/responses">responses</a>.<a href="https://pkg.go.dev/github.com/openai/openai-go/responses#ToolUnionParam">ToolUnionParam</a>
 - <a href="https://pkg.go.dev/github.com/openai/openai-go/responses">responses</a>.<a href="https://pkg.go.dev/github.com/openai/openai-go/responses#ToolChoiceFunctionParam">ToolChoiceFunctionParam</a>
+- <a href="https://pkg.go.dev/github.com/openai/openai-go/responses">responses</a>.<a href="https://pkg.go.dev/github.com/openai/openai-go/responses#ToolChoiceMcpParam">ToolChoiceMcpParam</a>
 - <a href="https://pkg.go.dev/github.com/openai/openai-go/responses">responses</a>.<a href="https://pkg.go.dev/github.com/openai/openai-go/responses#ToolChoiceOptions">ToolChoiceOptions</a>
 - <a href="https://pkg.go.dev/github.com/openai/openai-go/responses">responses</a>.<a href="https://pkg.go.dev/github.com/openai/openai-go/responses#ToolChoiceTypesParam">ToolChoiceTypesParam</a>
 - <a href="https://pkg.go.dev/github.com/openai/openai-go/responses">responses</a>.<a href="https://pkg.go.dev/github.com/openai/openai-go/responses#WebSearchToolParam">WebSearchToolParam</a>
@@ -696,6 +726,7 @@ Response Types:
 - <a href="https://pkg.go.dev/github.com/openai/openai-go/responses">responses</a>.<a href="https://pkg.go.dev/github.com/openai/openai-go/responses#ResponseWebSearchCallSearchingEvent">ResponseWebSearchCallSearchingEvent</a>
 - <a href="https://pkg.go.dev/github.com/openai/openai-go/responses">responses</a>.<a href="https://pkg.go.dev/github.com/openai/openai-go/responses#ToolUnion">ToolUnion</a>
 - <a href="https://pkg.go.dev/github.com/openai/openai-go/responses">responses</a>.<a href="https://pkg.go.dev/github.com/openai/openai-go/responses#ToolChoiceFunction">ToolChoiceFunction</a>
+- <a href="https://pkg.go.dev/github.com/openai/openai-go/responses">responses</a>.<a href="https://pkg.go.dev/github.com/openai/openai-go/responses#ToolChoiceMcp">ToolChoiceMcp</a>
 - <a href="https://pkg.go.dev/github.com/openai/openai-go/responses">responses</a>.<a href="https://pkg.go.dev/github.com/openai/openai-go/responses#ToolChoiceOptions">ToolChoiceOptions</a>
 - <a href="https://pkg.go.dev/github.com/openai/openai-go/responses">responses</a>.<a href="https://pkg.go.dev/github.com/openai/openai-go/responses#ToolChoiceTypes">ToolChoiceTypes</a>
 - <a href="https://pkg.go.dev/github.com/openai/openai-go/responses">responses</a>.<a href="https://pkg.go.dev/github.com/openai/openai-go/responses#WebSearchTool">WebSearchTool</a>