Generate Webhook Reference | Fern Documentation

Fern generates Webhook Reference documentation from an OpenAPI specification.

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

Configuration

Set up your project structure

Add your specification file to your /fern directory.

Add the Webhook Reference to your navigation

Add an api item to your navigation in docs.yml and list your spec under specs:

docs.yml

navigation:
  - api: Webhook Reference
    specs:
      - type: openapi
        path: ./openapi/openapi.yml

Or reference the spec in a generators.yml in the folder that contains your webhook definition:

generators.yml

api:
  path: openapi/openapi.yml

Then add the api item without specs, and use the api-name property to reference that folder:

docs.yml

navigation:
  - api: Webhook Reference
    api-name: webhooks-v1

Webhook entries in the sidebar show an HTTP method badge (e.g., POST) by default. To hide it on webhooks while keeping it on endpoints, set layout.hide-webhook-method-badges to true.

Customize the layout

For a full list of configuration options and layout customizations, see Customize API Reference layout.

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

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.

fern

fern.config.json

docs.yml

payment-webhooks

openapi

openapi.yml# Payment webhook OpenAPI spec

generators.yml

order-webhooks

openapi

openapi.yml# Order webhook OpenAPI spec

generators.yml

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:

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.

You must have the tags and example properties defined in your webhook specification.