API ReferencesGeneration

Generate Webhook Reference

View as Markdown

Fern generates Webhook Reference documentation from an OpenAPI specification or Fern 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

Configuration

1

Set up your project structure

For OpenAPI: Add your specification file to your /fern directory and create a generators.yml that references it:

generators.yml
1api:
2  path: openapi/openapi.yml

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

2

Add the Webhook Reference to your navigation

Add - api: Webhook Reference to your navigation in docs.yml:

docs.yml
1navigation:
2  - api: Webhook Reference
3    api-name: webhooks-v1

Use the api-name property to reference the folder containing your webhook definition.

3

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
1navigation:
2  - api: Payment Webhooks
3    api-name: payment-webhooks
4  - api: Order Webhooks
5    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
1navigation:
2  - api: Webhook Reference
3    api-name: webhooks-v1
4    layout:
5      - subpackage_plants.newPlantWebhook

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

For OpenAPI, you must have the tags and example properties defined in your webhook specification.