Webhooks | Fern Documentation

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

Using OpenAPI 3.1’s native webhook support (recommended)
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

1 webhooks:
2   newPlant:
3     post:
4       operationId: newPlantWebhook
5       requestBody:
6         description: Information about a new Plant in the system
7         content:
8           application/json:
9             schema:
10               $ref: '#/components/schemas/Plant'
11       responses:
12         '200':
13           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

1 paths: 
2   /payment/updated/: 
3     post: 
4       summary: Payment Initiated
5       operationId: initiatePayment
6       x-fern-webhook: true
7       requestBody:
8         content:
9           application/json:
10             schema:
11               type: object
12               properties:
13                 amount:
14                   type: number
15                 currency:
16                   $ref: '#/components/schemas/Currency'
17               required:
18                 - amount
19                 - currency

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.