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.

To create dedicated pages in your API reference documentation for each webhook event, include tags and complete example data in your schema. Then, add a reference in your docs.yml.

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.

To create dedicated pages in your API reference documentation for each webhook event, include tags and complete example data in your schema. Then, add a reference in your docs.yml.

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.