chore: documented webhooks native support (#330)

Co-authored-by: Danny Sheridan <[email protected]>

Author: Ryan-Amirthan

fern/docs.yml

@@ -469,6 +469,9 @@ redirects:
   - source: /learn/api-definition/openapi/:slug*
     destination: /learn/openapi-definition/:slug*
     permanent: true
+  - source: /learn/openapi-definition/extensions/webhooks
+    destination: /learn/openapi-definition/endpoints/webhooks
+    permanent: true
 
   # API Definition Fern specific redirects first
   - source: /learn/api-definition/fern/endpoints/:slug*
@@ -546,3 +549,4 @@ redirects:
   - source: /learn/api-reference/tokens/:slug*
     destination: /learn/cli-api-reference/api-reference/tokens/:slug*
     permanent: true
+

fern/products/docs/pages/api-references/generate-webhook-ref.mdx

@@ -3,7 +3,16 @@ title: Generate your Webhook Reference
 description: Use Fern Docs to generate your Webhook Reference documentation from your API definition, using your choice of either OpenAPI or Fern Definition.
 ---
 
-Similar to API References, Fern Docs can automatically generate your Webhook Reference documentation from your API definition. Simply add `x-fern-webhook: true` to the webhook definitions in your OpenAPI specification or define `webhooks` in your Fern Definition and Fern will generate comprehensive documentation for all your webhooks! 
+Similar to API References, Fern Docs can automatically generate your Webhook Reference documentation from your API definition. 
+
+Fern supports webhooks through:
+- **OpenAPI 3.1+**: Use the native `webhooks` field with an `operationId` (recommended)
+- **OpenAPI 3.0**: Use the `x-fern-webhook: true` extension 
+- **Fern Definition**: Define `webhooks` in your specification
+
+For more information on how to define webhooks, see:
+- [Webhooks in OpenAPI](../../openapi-definition/endpoints/webhooks)
+- [Webhooks in Fern Definition](../../fern-definition/webhooks)
 
 Example:
 

fern/products/openapi-def/openapi-def.yml

@@ -11,6 +11,8 @@ navigation:
       - page: HTTP JSON Endpoints
         path: ./pages/endpoints/rest.mdx
         slug: http
+      - page: Webhooks
+        path: ./pages/webhooks.mdx
       - page: Multipart Form Uploads
         path: ./pages/endpoints/multipart.mdx
         slug: multipart
@@ -20,8 +22,6 @@ navigation:
   - section: Extensions
     slug: extensions
     contents:
-      - page: Webhooks
-        path: ./pages/webhooks.mdx
       - page: Audiences
         path: ./pages/extensions/audiences.mdx
       - page: SDK Method Names

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
+title: Webhooks
+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 {4}
+webhooks:
+  newPlant:
+    post:
+      operationId: newPlantWebhook
+      requestBody:
+        description: Information about a new Plant in the system
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Plant'
+      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: