Add Fern Definition syntax for generating individual pages per webhook event (Docs, API Definitions) (#685)

Author: devalog

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

@@ -63,3 +63,24 @@ You can inline the schema of the payload by doing the following:
   ```
 </CodeBlock>
 
+## Generate webhook reference
+
+Fern Docs can automatically generate your webhook reference documentation from your definition. Set this up in your `docs.yml` file. 
+
+Your webhook reference can be a single documentation page:
+
+```yml docs.yml
+navigation:
+  - api: Webhook Reference # Display name for this page
+    api-name: webhooks-v1 # Directory containing webhook definition
+```
+
+Or you can configure individual documentation pages per webhook event:
+
+```yaml title="docs.yml"
+navigation:
+  - subpackage_api.newPlantWebhook # Format: subpackage_{name-of-api}.{webhook-event-name}
+```
+
+For more information on how to configure your webhook reference in `docs.yml`, see [Generate your webhook reference](/docs/api-references/generate-webhook-reference).
+

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

@@ -8,15 +8,10 @@ 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
+## 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.
 
-To create dedicated pages in your API reference documentation for each webhook
-event, include `tags` and complete `example` data in your schema. Then, [add a
-reference in your
-`docs.yml`](/docs/api-references/generate-webhook-reference#create-individual-documentation-pages-for-each-webhook-event-openapi).
-
 ```yaml openapi.yml {4, 7-8, 42-48}
 webhooks:
   newPlant:
@@ -71,15 +66,10 @@ webhooks:
           description: Return a 200 status to indicate that the data was received successfully
 ```
 
-## Fern Webhook Extension
+## 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.
 
-To create dedicated pages in your API reference documentation for each webhook
-event, include `tags` and complete `example` data in your schema. Then, [add a
-reference in your
-`docs.yml`](/docs/api-references/generate-webhook-reference#create-individual-documentation-pages-for-each-webhook-event-openapi).
-
 ```yaml openapi.yml {6-8, 23-25}
 paths: 
   /payment/updated/: 
@@ -112,3 +102,24 @@ paths:
 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>
+
+## Generate webhook reference
+
+Fern Docs can automatically generate your webhook reference documentation from your definition. Set this up in your `docs.yml` file. 
+
+Your webhook reference can be a single documentation page:
+
+```yml docs.yml
+navigation:
+  - api: Webhook Reference # Display name for this page
+    api-name: webhooks-v1 # Name of webhook definition directory
+```
+
+Or you can configure individual documentation pages per webhook event:
+
+```yaml title="docs.yml"
+navigation:
+  - subpackage_plants.newPlantWebhook # subpackage_{tag}.{webhook-event-name}
+```
+
+For more information on how to configure your webhook reference in `docs.yml`, see [Generate your webhook reference](/docs/api-references/generate-webhook-reference).

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

@@ -1,9 +1,9 @@
 ---
-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.
+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. 
+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)
@@ -14,7 +14,9 @@ For more information on how to define webhooks, see:
 - [Webhooks in OpenAPI](../../openapi-definition/endpoints/webhooks)
 - [Webhooks in Fern Definition](../../fern-definition/webhooks)
 
-Example:
+## Configure your webhook reference
+
+Add a page title (`api`) and reference the name of the directory where your where your webhook definition is located (`api-name`). 
 
 ```yml docs.yml {11-12}
 navigation:
@@ -31,9 +33,9 @@ navigation:
     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).
+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
+### Directory structure
 Your webhooks should be defined in a dedicated folder within your Fern project:
 
 <Tabs>
@@ -73,7 +75,7 @@ You can read more about how to define webhooks in your Fern Definition [here](/l
 </Tab>
 </Tabs>
 
-### Include more than one Webhook Reference
+### Include more than one webhook reference
 To include multiple webhook definitions in your documentation, use the `webhook-name` property:
 
 ```yaml title="docs.yml"
@@ -99,15 +101,34 @@ fern/
           └── generators.yml
 ```
 
-### Create individual documentation pages for each webhook event (OpenAPI)
+### Create individual documentation pages for each webhook event
 
-To display each webhook event as an individual page with rich examples, you need to define `tags` and `example` [in your webhook specification](/api-definitions/openapi/endpoints/webhooks) (or [overrides file](/api-definitions/overview/overrides)).
+To display each webhook event as an individual page with rich examples:
 
-Then, reference individual webhook pages using the `subpackage_{tag}.{webhook-event-name}` format, where:
+<Tabs>
+<Tab title="OpenAPI">
+Reference individual webhook pages using the `subpackage_{tag}.{webhook-event-name}` format, where:
 - `{tag}` is the first tag (lowercase) from your webhook definition
 - `{webhook-event-name}` is the `operationId` from your webhook definition
 
 ```yaml title="docs.yml"
 navigation:
   - subpackage_plants.newPlantWebhook
 ```
+
+<Note>
+  For OpenAPI, you must have the `tags` and `example` properties defined [in your webhook specification](/api-definitions/openapi/endpoints/webhooks).
+</Note>
+
+</Tab>
+<Tab title="Fern Definition">
+Reference the individual webhook event using the `subpackage_{name}.{webhook-event-name}` format, where:
+- `{name}` is the name of your API as defined in the `api.yml` file for your webhook definition.
+- `{webhook-event-name}` is the identifier from your webhook definition
+
+```yaml title="docs.yml"
+navigation:
+  - subpackage_api.newPlantWebhook
+```
+</Tab>
+</Tabs>