diff --git a/fern/products/api-def/ferndef-pages/webhooks.mdx b/fern/products/api-def/ferndef-pages/webhooks.mdx index 399c3c2a1..3b164f863 100644 --- a/fern/products/api-def/ferndef-pages/webhooks.mdx +++ b/fern/products/api-def/ferndef-pages/webhooks.mdx @@ -63,3 +63,24 @@ You can inline the schema of the payload by doing the following: ``` +## 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). + diff --git a/fern/products/api-def/openapi-pages/webhooks.mdx b/fern/products/api-def/openapi-pages/webhooks.mdx index 841d1e810..92ff56d62 100644 --- a/fern/products/api-def/openapi-pages/webhooks.mdx +++ b/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. + +## 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). \ No newline at end of file diff --git a/fern/products/docs/pages/api-references/generate-webhook-ref.mdx b/fern/products/docs/pages/api-references/generate-webhook-ref.mdx index 43798975d..f2ba56202 100644 --- a/fern/products/docs/pages/api-references/generate-webhook-ref.mdx +++ b/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: @@ -73,7 +75,7 @@ You can read more about how to define webhooks in your Fern Definition [here](/l -### 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,11 +101,13 @@ 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: + + +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 @@ -111,3 +115,20 @@ Then, reference individual webhook pages using the `subpackage_{tag}.{webhook-ev navigation: - subpackage_plants.newPlantWebhook ``` + + + For OpenAPI, you must have the `tags` and `example` properties defined [in your webhook specification](/api-definitions/openapi/endpoints/webhooks). + + + + +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 +``` + +