Generate your Webhook Reference | Fern Documentation

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:

Example:

docs.yml

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:

OpenAPI

Fern Definition

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

If you’re using OpenAPI, your generators.yml file should point to your OpenAPI specification:

generators.yml

1 api:
2   path: openapi/openapi.yml

You can read more about how to define webhooks in your OpenAPI specification here.

Include more than one Webhook Reference

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

docs.yml

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