# Generate your webhook reference

> 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.

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)

## 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:
  - 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">
    <Files>
      <Folder name="fern" defaultOpen>
        <Folder name="apis" defaultOpen>
          <Folder name="webhooks-v1" defaultOpen highlighted comment="Webhook definition">
            <Folder name="openapi" defaultOpen>
              <File name="openapi.yml" />
            </Folder>

            <File name="generators.yml" />
          </Folder>

          <Folder name="api-v1" comment="Regular API endpoints" />
        </Folder>
      </Folder>
    </Files>

    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-definitions/openapi/endpoints/webhooks).
  </Tab>

  <Tab title="Fern Definition">
    <Files>
      <Folder name="fern" defaultOpen>
        <Folder name="apis" defaultOpen>
          <Folder name="webhooks-v1" defaultOpen highlighted comment="Webhook definition">
            <Folder name="definition" defaultOpen>
              <File name="api.yml" />

              <File name="webhooks.yml" />
            </Folder>

            <File name="generators.yml" />
          </Folder>

          <Folder name="api-v1" comment="Regular API endpoints" />
        </Folder>
      </Folder>
    </Files>

    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 `api-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:

<Files>
  <Folder name="fern" defaultOpen>
    <Folder name="apis" defaultOpen>
      <Folder name="payment-webhooks" defaultOpen highlighted comment="Payment webhook definitions">
        <Folder name="openapi">
          <File name="openapi.yml" comment="Payment webhook OpenAPI spec" />
        </Folder>

        <File name="generators.yml" />
      </Folder>

      <Folder name="order-webhooks" defaultOpen highlighted comment="Order webhook definitions">
        <Folder name="openapi">
          <File name="openapi.yml" comment="Order webhook OpenAPI spec" />
        </Folder>

        <File name="generators.yml" />
      </Folder>
    </Folder>
  </Folder>
</Files>

### Create individual documentation pages for each webhook event

To display each webhook event as an individual page with rich examples:

<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>