From acb92c80ee0c5945d89abc2a87c88773853708d4 Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Wed, 9 Jul 2025 13:26:02 -0700
Subject: [PATCH 1/2] add webhooks section

---
 api-playground/openapi-setup.mdx | 30 +++++++++++++++++++++++++++---
 1 file changed, 27 insertions(+), 3 deletions(-)

diff --git a/api-playground/openapi-setup.mdx b/api-playground/openapi-setup.mdx
index 97809e50c..dad94f759 100644
--- a/api-playground/openapi-setup.mdx
+++ b/api-playground/openapi-setup.mdx
@@ -4,7 +4,7 @@ description: "Reference OpenAPI endpoints in your docs pages"
 icon: "file-json"
 ---
 
-OpenAPI is a specification for describing REST APIs. Mintlify supports OpenAPI 3.0+ documents to generate interactive API documentation and keep it up to date.
+OpenAPI is a specification for describing APIs. Mintlify supports OpenAPI 3.0+ documents to generate interactive REST API documentation, and OpenAPI 3.1+ for documenting webhooks.
 
 ## Add an OpenAPI specification file
 
@@ -186,8 +186,6 @@ version: "version-string" (not required)
 
 <Note>
   The method and path must exactly match the definition in your OpenAPI specification. If the endpoint doesn't exist in the OpenAPI file, the page will be empty.
-
-  For webhooks, use `webhook` (case insensitive) instead of the HTTP method (like `GET` or `POST`) in your reference.
 </Note>
 
 ### Autogenerate `MDX` files
@@ -239,3 +237,29 @@ openapi-schema: "schema-key"
 ```
 
 </CodeGroup>
+
+## Webhooks
+
+Webhooks are HTTP callbacks that your API sends to notify external systems when events occur. If your OpenAPI 3.1+ document defines webhooks, you can document them alongside your regular API endpoints.
+
+### Define webhooks in your OpenAPI specification
+
+Add a `webhooks` field to your OpenAPI document alongside the `paths` field.
+
+For more information on defining webhooks, see [Webhooks](https://spec.openapis.org/oas/v3.1.0#oasWebhooks) in the OpenAPI documentation.
+
+### Reference webhooks in MDX files
+
+When creating MDX pages for webhooks, use `webhook` instead of HTTP methods like `GET` or `POST`:
+
+```mdx
+---
+title: "Example webhook"
+description: "Triggered when an event occurs"
+openapi: "path/to/openapi-file webhook example-webhook-name"
+---
+```
+
+<Note>
+  The webhook name must exactly match the key defined in your OpenAPI specification's `webhooks` field.
+</Note>

From 73d131c3f591b118a0aed10157f9e11b17b5314d Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Thu, 10 Jul 2025 19:58:55 -0700
Subject: [PATCH 2/2] put version requirements in context

---
 api-playground/openapi-setup.mdx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/api-playground/openapi-setup.mdx b/api-playground/openapi-setup.mdx
index dad94f759..9115a21b2 100644
--- a/api-playground/openapi-setup.mdx
+++ b/api-playground/openapi-setup.mdx
@@ -4,7 +4,7 @@ description: "Reference OpenAPI endpoints in your docs pages"
 icon: "file-json"
 ---
 
-OpenAPI is a specification for describing APIs. Mintlify supports OpenAPI 3.0+ documents to generate interactive REST API documentation, and OpenAPI 3.1+ for documenting webhooks.
+OpenAPI is a specification for describing APIs. Mintlify supports OpenAPI 3.0+ documents to generate interactive API documentation and keep it up to date.
 
 ## Add an OpenAPI specification file
 
@@ -240,7 +240,7 @@ openapi-schema: "schema-key"
 
 ## Webhooks
 
-Webhooks are HTTP callbacks that your API sends to notify external systems when events occur. If your OpenAPI 3.1+ document defines webhooks, you can document them alongside your regular API endpoints.
+Webhooks are HTTP callbacks that your API sends to notify external systems when events occur. Webhooks are supported in OpenAPI 3.1+ documents.
 
 ### Define webhooks in your OpenAPI specification