***

title: Generate Webhook Reference
description: >-
Use Fern Docs to generate your Webhook Reference documentation from an OpenAPI
spec or Fern Definition.
------------------------

Fern generates Webhook Reference documentation from an [OpenAPI specification](/learn/api-definitions/openapi/endpoints/webhooks) or [Fern Definition](/learn/api-definitions/ferndef/webhooks).

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

## Configuration

<Steps>
  <Step title="Set up your project structure">
    For **OpenAPI**: Add your specification file to your `/fern` directory and create a `generators.yml` that references it:

    ```yaml generators.yml
    api:
      path: openapi/openapi.yml
    ```

    For **Fern Definition**: Add a `definition/` directory with your webhook definition files (Fern auto-detects this).
  </Step>

  <Step title="Add the Webhook Reference to your navigation">
    Add `- api: Webhook Reference` to your navigation in `docs.yml`:

    ```yml docs.yml
    navigation:
      - api: Webhook Reference
        api-name: webhooks-v1
    ```

    Use the `api-name` property to reference the folder containing your webhook definition.
  </Step>

  <Step title="Customize the layout">
    For a full list of configuration options and layout customizations, see [Customize API Reference layout](/learn/docs/api-references/customize-api-reference-layout).
  </Step>
</Steps>

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

### Include more than one Webhook Reference

To include multiple webhook definitions in your documentation, use the `api-name` property. The `api-name` corresponds to the folder name containing your webhook definition.

<Files>
  <Folder name="fern" defaultOpen>
    <File name="fern.config.json" />

    <File name="docs.yml" />

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

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

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

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

```yaml title="docs.yml"
navigation:
  - api: Payment Webhooks
    api-name: payment-webhooks
  - api: Order Webhooks
    api-name: order-webhooks
```

### Reference individual webhook events

To display each webhook event as an individual page, reference it in the `layout` using the `subpackage_{tag}.{webhook-event-name}` format:

<Tabs>
  <Tab title="OpenAPI">
    ```yaml title="docs.yml"
    navigation:
      - api: Webhook Reference
        api-name: webhooks-v1
        layout:
          - subpackage_plants.newPlantWebhook
    ```

    Where `{tag}` is the first tag (lowercase) and `{webhook-event-name}` is the `operationId` from your webhook definition.

    <Note>
      For OpenAPI, you must have the `tags` and `example` properties defined [in your webhook specification](/learn/api-definitions/openapi/endpoints/webhooks).
    </Note>
  </Tab>

  <Tab title="Fern Definition">
    ```yaml title="docs.yml"
    navigation:
      - api: Webhook Reference
        api-name: webhooks-v1
        layout:
          - subpackage_api.newPlantWebhook
    ```

    Where `{name}` is the name of your API as defined in `api.yml` and `{webhook-event-name}` is the identifier from your webhook definition.
  </Tab>
</Tabs>