Add webhooks section to OpenAPI setup

api-playground/openapi-setup.mdx

@@ -4,7 +4,7 @@
 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
 
@@ -25,7 +25,7 @@
 
 ### Specifying the URL for your API
 
 To enable Mintlify features like the API playground, add a `servers` field to your OpenAPI document with your API's base URL.
 
 ```json
 {
@@ -186,16 +186,14 @@
 
 <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
 
 Use our Mintlify [scraper](https://www.npmjs.com/package/@mintlify/scraping) to autogenerate `MDX` pages for large OpenAPI documents.
 
 <Note>
   Your OpenAPI document must be valid or the files will not autogenerate.
 </Note>
 
 The scraper generates:
@@ -207,12 +205,12 @@
 <Steps>
   <Step title="Generate `MDX` files.">
     ```bash
     npx @mintlify/scraping@latest openapi-file <path-to-openapi-file>
     ```
   </Step>
   <Step title="Specify an output folder.">
     ```bash
     npx @mintlify/scraping@latest openapi-file <path-to-openapi-file> -o api-reference
     ```
 
     Add the `-o` flag to specify a folder to populate the files into. If a folder is not specified, the files will populate in the working directory.
@@ -239,3 +237,29 @@
 ```
 
 </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>