🌿 Fern Scribe: Fern supports Webhooks as part of openapi 3.1, we ...

fern/products/fern-def/pages/webhooks.mdx

@@ -4,11 +4,11 @@ description: Learn how to define webhooks in the Fern Definition
 ---
 
 In Fern, you can specify webhooks in your API definition. The webhooks will be included 
-in both the generated SDKs and the API documentation.
+in both the generated SDKs and the API documentation. Fern supports both its native webhook definition format and OpenAPI 3.1 webhooks.
 
-## Webhook definition
+## Fern Webhook Definition
 
-Each webhook defines:
+Each webhook in the Fern format defines:
 
 1. **Method**: The HTTP Method that the webhook will use (either `GET` or `POST`)
 2. **Headers**: The headers that the webhook will send
@@ -37,9 +37,9 @@ Each webhook defines:
   ```
 </CodeBlock>
 
-### Inlined payloads
+### Inlined Payloads
 
-You can inline the schema of the payload by doing the following: 
+You can inline the schema of the payload in the Fern format:
 
 <CodeBlock title='webhooks.yml'>
   ```yaml
@@ -63,3 +63,26 @@ You can inline the schema of the payload by doing the following:
   ```
 </CodeBlock>
 
+## OpenAPI 3.1 Webhooks
+
+Fern also supports OpenAPI 3.1 webhook definitions. When using OpenAPI format, each webhook operation must include an `operationId`:
+
+<CodeBlock title='openapi.yml'>
+  ```yaml
+  webhooks:
+    newPet:
+      post:
+        operationId: newPetWebhook
+        requestBody:
+          description: Information about a new pet in the system
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Pet'
+        responses:
+          '200':
+            description: Return a 200 status to indicate that the data was received successfully
+  ```
+</CodeBlock>
+
+The webhook definition follows the OpenAPI 3.1 specification, with the key requirement that each webhook operation must include an `operationId` for proper SDK generation.

fern/products/openapi-def/pages/webhooks.mdx

@@ -1,9 +1,36 @@
 ---
 title: Define Webhooks in OpenAPI
-subtitle: Use the `x-fern-webhook` extension to define webhooks in your OpenAPI spec
+subtitle: Define webhooks using OpenAPI 3.1+ native webhook support or Fern's extensions
 ---
 
-To define a webhook in your OpenAPI specification, add the `x-fern-webhook: true` extension to your endpoint. OpenAPI 3.0.0 or higher is required. Fern will treat the `requestBody` as the webhook payload. 
+Fern supports two methods for defining webhooks in your OpenAPI specification:
+
+1. Using OpenAPI 3.1's native webhook support (recommended)
+2. Using Fern's `x-fern-webhook` extension
+
+## OpenAPI 3.1 Webhooks
+
+For OpenAPI 3.1 specifications, use the `webhooks` top-level field to define your webhook operations. Each webhook requires an `operationId` to be properly processed by Fern.
+
+```yaml openapi.yml
+webhooks:
+  newPet:
+    post:
+      operationId: newPetWebhook
+      requestBody:
+        description: Information about a new pet in the system
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Pet'
+      responses:
+        '200':
+          description: Return a 200 status to indicate that the data was received successfully
+```
+
+## Fern Webhook Extension
+
+For OpenAPI 3.0, use the `x-fern-webhook: true` extension to define webhooks. Fern will treat the `requestBody` as the webhook payload.
 
 ```yaml openapi.yml {6}
 paths: 
@@ -27,7 +54,7 @@ paths:
                 - currency 
 ```
 
-<Info> 
+<Info>
 The path that you choose when defining a webhook can be arbitrary. Since webhooks 
 can be sent to any server, Fern just ignores the path.
-</Info>
+</Info>