Generate your Webhook Reference

Similar to API References, Fern Docs can automatically generate your Webhook Reference documentation from your API definition. Simply add x-fern-webhook: true to the webhook definitions in your OpenAPI specification or define webhooks in your Fern Definition and Fern will generate comprehensive documentation for all your webhooks!

Example:

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