OpenAPIEndpoints

Webhooks

Define webhooks using OpenAPI 3.1+ native webhook support or Fern’s extensions

Fern supports two methods for defining webhooks in your OpenAPI specification:

  1. Using OpenAPI 3.1’s native webhook support (recommended)
  2. Using Fern’s x-fern-webhook extension

OpenAPI 3.1 webhooks

For OpenAPI 3.1 specifications, use the webhooks top-level field to define your webhook operations. Each webhook requires an operationId to be properly processed by Fern.

openapi.yml
1webhooks:
2  newPlant:
3    post:
4      operationId: newPlantWebhook # Defines webhook
5      summary: New Plant Added
6      description: Information about a new plant that was added to the store
7      tags:
8        - Plants # Creates dedicated page
9      requestBody:
10        description: The plant data when a new plant is added
11        content:
12          application/json:
13            schema:
14              description: The Webhook payload for when a new plant is added to the store
15              properties:
16                triggerType:
17                  description: The type of event that triggered the request
18                  type: string
19                  example: "new_plant"
20                payload:
21                  type: object
22                  description: The payload of data sent from the plant store
23                  properties:
24                    plantId:
25                      type: string
26                      description: The unique identifier for the plant
27                      example: "64f1a2b3c5d6e7f8a9b0c1d2"
28                    name:
29                      type: string
30                      description: The name of the plant
31                      example: "Monstera Deliciosa"
32                    price:
33                      type: number
34                      format: float
35                      description: The price of the plant in dollars
36                      example: 29.99
37                    addedAt:
38                      type: string
39                      format: date-time
40                      description: The timestamp when the plant was added
41                      example: "2024-01-15T10:30:00.000Z"
42              example: # Full payload example for docs
43                triggerType: "new_plant"
44                payload:
45                  plantId: "64f1a2b3c5d6e7f8a9b0c1d2"
46                  name: "Monstera Deliciosa"
47                  price: 29.99
48                  addedAt: "2024-01-15T10:30:00.000Z"
49      responses:
50        '200':
51          description: Return a 200 status to indicate that the data was received successfully

Fern webhook extension

For OpenAPI 3.0, use the x-fern-webhook: true extension to define webhooks. Fern will treat the requestBody as the webhook payload.

openapi.yml
1paths: 
2  /payment/updated/: 
3    post: 
4      summary: Payment Initiated
5      operationId: initiatePayment
6      tags:
7        - Payments # Creates dedicated page
8      x-fern-webhook: true # Defines webhooks
9      requestBody:
10        content:
11          application/json:
12            schema:
13              type: object
14              properties:
15                amount:
16                  type: number
17                  example: 99.99
18                currency:
19                  $ref: '#/components/schemas/Currency'
20              required:
21                - amount
22                - currency
23              example: # Full payload example for docs
24                amount: 99.99
25                currency: "USD"

The path that you choose when defining a webhook can be arbitrary. Since webhooks can be sent to any server, Fern just ignores the path.

Generate webhook reference

Fern Docs can automatically generate your webhook reference documentation from your definition. Set this up in your docs.yml file.

Your webhook reference can be a single documentation page:

docs.yml
1navigation:
2  - api: Webhook Reference # Display name for this page
3    api-name: webhooks-v1 # Name of webhook definition directory

Or you can configure individual documentation pages per webhook event:

docs.yml
1navigation:
2  - subpackage_plants.newPlantWebhook # subpackage_{tag}.{webhook-event-name}

For more information on how to configure your webhook reference in docs.yml, see Generate your webhook reference.