Generate your webhook reference

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
• Webhooks in Fern Definition

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

1
navigation:
2
  - section: Introduction
3
    contents:
4
      - page: Getting Started
5
        path: ../introduction/getting-started.md
6
      - page: Authentication
7
        path: ../introduction/authentication.md
8
  - api: API Reference
9
    api-name: api-v1
10
    display-errors: true
11
  - api: Webhook Reference
12
    api-name: webhooks-v1

For a real-world example of webhook documentation generated from an API definition, check out Webflow’s webhooks.

Directory structure

Your webhooks should be defined in a dedicated folder within your Fern project:

$
fern/
>
  └── apis/
>
      ├── webhooks-v1/           # Webhook definition
>
      │   ├── openapi/       
>
      │   │   └── openapi.yml
>
      │   └── generators.yml
>
      └── api-v1/               # Regular API endpoints

1
api:
2
  path: openapi/openapi.yml

Include more than one webhook reference

To include multiple webhook definitions in your documentation, use the webhook-name property:

1
navigation:
2
  - api: Payment Webhooks
3
    api-name: payment-webhooks
4
  - api: Order Webhooks
5
    api-name: order-webhooks

When using multiple webhook definitions, organize them in separate directories within your Fern project:

$
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

Create individual documentation pages for each webhook event

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

1
navigation:
2
  - subpackage_plants.newPlantWebhook