feat(docs): Document configuring a webhook reference in Fern Docs (#5778

)

* feat(docs): Document configuring a webhook reference in Fern Docs

* update webhook reference

* add to nav

* small updates

---------

Co-authored-by: fern-bot <info@buildwithfern.com>

fern/docs.yml

@@ -499,6 +499,9 @@ navigation:
           - page: Write Markdown in API Reference
             icon: fa-regular fa-pencil
             path: ./pages/docs/api-references/api-ref-content.mdx
+          - page: Generate Webhook Reference
+            icon: fa-regular fa-webhook
+            path: ./pages/docs/api-references/generate-webhook-ref.mdx
 
       - section: Integrations
         slug: integrations

fern/pages/api-definition/openapi/webhooks.mdx

@@ -3,10 +3,9 @@ title: Define Webhooks in OpenAPI
 subtitle: Use the `x-fern-webhook` extension to define webhooks in your OpenAPI spec
 ---
 
-Simply define a path in your OpenAPI, and add the extension `x-fern-webhook`. Fern will 
-treat the `requestBody` as the webhook payload. 
+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. 
 
-```yaml openapi.yml
+```yaml openapi.yml {6}
 paths: 
   /payment/updated/: 
     post: 

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

@@ -0,0 +1,91 @@
+---
+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! 
+
+Example:
+
+```yml docs.yml {11-12}
+navigation:
+  - section: Introduction
+    contents:
+      - page: Getting Started
+        path: ../introduction/getting-started.md
+      - page: Authentication
+        path: ../introduction/authentication.md
+  - api: API Reference
+    api-name: api-v1
+    display-errors: true
+  - api: Webhook Reference
+    api-name: webhooks-v1
+```
+
+For a real-world example of webhook documentation generated from an API definition, check out [Webflow's Webhooks](https://developers.webflow.com/data/reference/webhooks/events/form-submission).
+
+### Directory Structure
+Your webhooks should be defined in a dedicated folder within your Fern project:
+
+<Tabs>
+<Tab title="OpenAPI">
+```bash
+fern/
+  └── apis/
+      ├── webhooks-v1/           # Webhook definition
+      │   ├── openapi/       
+      │   │   └── openapi.yml
+      │   └── generators.yml
+      └── api-v1/               # Regular API endpoints
+```
+
+If you're using OpenAPI, your `generators.yml` file should point to your OpenAPI specification:
+
+```yml generators.yml
+api:
+  path: openapi/openapi.yml
+```
+
+You can read more about how to define webhooks in your OpenAPI specification [here](/learn/api-definition/openapi/webhooks).
+</Tab>
+<Tab title="Fern Definition">
+```bash
+fern/
+  └── apis/
+      ├── webhooks-v1/           # Webhook definition
+      │   ├── definition/  
+      │   │   ├── api.yml    
+      │   │   └── webhooks.yml
+      │   └── generators.yml
+      └── api-v1/               # Regular API endpoints
+```
+
+You can read more about how to define webhooks in your Fern Definition [here](/learn/api-definition/fern/webhooks).
+</Tab>
+</Tabs>
+
+### Include more than one Webhook Reference
+To include multiple webhook definitions in your documentation, use the `webhook-name` property:
+
+```yaml title="docs.yml"
+navigation:
+  - api: Payment Webhooks
+    api-name: payment-webhooks
+  - api: Order Webhooks
+    api-name: order-webhooks
+```
+
+When using multiple webhook definitions, organize them in separate directories within your Fern project:
+
+```bash
+fern/
+  └── apis/
+      ├── payment-webhooks/     # Payment webhook definitions
+      │   ├── openapi/
+      │   │   └── openapi.yml   # Payment webhook OpenAPI spec
+      │   └── generators.yml
+      └── order-webhooks/       # Order webhook definitions
+          ├── openapi/
+          │   └── openapi.yml   # Order webhook OpenAPI spec
+          └── generators.yml
+```