🌿 Fern Scribe: Fern supports Webhooks as part of openapi 3.1, we ...

[github-actions]

🌿 Fern Scribe Documentation Update

Original Request: Fern supports Webhooks as part of openapi 3.1, we need to document that.

Files Updated:

• fern/products/fern-def/pages/webhooks.mdx
• fern/products/openapi-def/pages/webhooks.mdx

Priority: Medium

Related Discussion: https://buildwithfern.slack.com/archives/C07EQ2VEFU5/p1748360947074069?thread_ts=1748360905.972659&cid=C07EQ2VEFU5

Additional Context: we currently support the OpenAPI 3.1 webhooks! For example in the openapi you referenced. You can use it directly if you add an operationId to each webhook operation:
webhooks:

Each webhook needs a name

newPet:
# This is a Path Item Object, the only difference is that the request is initiated by the API provider
post:
operationId: newPetWebhook
requestBody:
description: Information about a new pet in the system
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
responses:
'200':
description: Return a 200 status to indicate that the data was received successfully

⚠️ Files with MDX Validation Issues

The following files could not be updated due to MDX validation failures after 3 attempts:

1. /learn/docs/api-references/generate-webhook-reference (Generate Webhook Reference)

• URL: https://fern-api.docs.buildwithfern.com/learn/docs/api-references/generate-webhook-reference
• Validation Issues:
  • Mismatched Tab tags: 3 opening, 2 closing

Suggested Content (needs manual MDX fixes):

---
title: Generate your Webhook Reference
description: Use Fern Docs to generate your Webhook Reference documentation from your API definition, using your choice of either OpenAPI or Fern Definition.
---

Similar to API References, Fern Docs can automatically generate your Webhook Reference documentation from your API definition. You can define webhooks using either OpenAPI 3.1's native webhook support or Fern Definition format.

### OpenAPI 3.1 Webhooks
If you're using OpenAPI 3.1, you can define webhooks directly in your specification using the `webhooks` field. Each webhook operation requires an `operationId`:

```yaml
webhooks:
  newPet:
    post:
      operationId: newPetWebhook
      requestBody:
        description: Information about a new pet in the system
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pet'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully

For OpenAPI 3.0, you can use the x-fern-webhook: true extension to mark endpoints as webhooks.

Setting Up Your Documentation

Example documentation configuration:

navigation:
  - section: Introduction
    contents:
      - page: Getting Started
        path: ../introduction/getting-started.md
      - page: Authentication
        path: ../introduction/authentication.md
  - api: API Reference
    api-name: api-v1
    display-errors: true
  - api: Webhook Reference
    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:

```bash 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:

api:
  path: openapi/openapi.yml

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

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

You can read more about how to define webhooks in your Fern Definition here.

Include more than one Webhook Reference

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

navigation:
  - api: Payment Webhooks
    api-name: payment-webhooks
  - api: Order Webhooks
    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

**Note**: These files require manual review and correction of their MDX component structure before the content can be applied.

---
*This PR was automatically generated by Fern Scribe based on issue #327*

**Please review the changes carefully before merging.**

[github-actions]

This PR is stale because it has been open 25 days with no activity. Remove stale label or comment or this will be closed in 5 days.