Webhooks

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 # 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

1 paths: 
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

1 navigation:
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

1 navigation:
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.

SDK signature verification

Use the x-fern-webhook-signature extension to configure webhook signature verification. When configured, Fern generates SDK utilities that allow users to verify webhook signatures and ensure events originate from your API.

Configuration can be set at the document level (applies to all webhook endpoints) or per-endpoint (overrides the document-level default). Both levels accept the same configuration options.

Fern supports two verification methods: HMAC (symmetric key verification using shared secrets) and Asymmetric (public key verification using RSA, ECDSA, or Ed25519 keys).

Document-level

Per-endpoint override

openapi.yml

1 x-fern-webhook-signature:
2   type: hmac
3   header: x-webhook-signature
4   algorithm: sha256
5   encoding: hex
6 
7 paths:
8   /webhooks/payment:
9     post:
10       x-fern-webhook: true
11       # Inherits document-level signature config
12 
13   /webhooks/order:
14     post:
15       x-fern-webhook: true
16       # Inherits document-level signature config

Configuration options

Common fields

These fields apply to both HMAC and asymmetric verification.

type

'hmac' | 'asymmetric'Required

The signature verification method. Use hmac for symmetric key verification with shared secrets, or asymmetric for public key verification.

stringRequired

The HTTP header containing the signature. For example, x-webhook-signature or x-hub-signature-256.

encoding

'base64' | 'hex'Required

The encoding format of the signature value in the header.

signature-prefix

string

A prefix to strip from the signature header value before verification. For example, "sha256=" or "rsa=".

timestamp.header

stringRequired

HTTP header containing the delivery timestamp.

timestamp.format

'unix-seconds' | 'unix-millis' | 'iso8601'Required

Format of the timestamp value in the header.

timestamp.tolerance

integerDefaults to 300

Allowed clock skew in seconds. Requests with timestamps outside this window are rejected.

HMAC fields

These fields apply when type is set to hmac.

algorithm

'sha256' | 'sha1' | 'sha384' | 'sha512'Required

The HMAC hash algorithm for signature computation. sha256 is recommended. sha1 is deprecated and should only be used for legacy compatibility.

payload-format.components

list of stringsRequired

Ordered list of payload components to concatenate before hashing. Available components:

Component	Description
`body`	Raw request body
`timestamp`	Timestamp value from timestamp header
`notification-url`	The webhook/callback URL
`message-id`	Provider-assigned message identifier

payload-format.delimiter

stringRequired

String used to join the components. Use "." for timestamp-prefixed payloads or "" for direct concatenation.

Asymmetric fields

These fields apply when type is set to asymmetric.

asymmetric-algorithm

The asymmetric signing algorithm. rsa-sha256 and ecdsa-sha256 are widely supported defaults. ed25519 is a modern, efficient option.

jwks-url

string

JSON Web Key Set (JWKS) endpoint URL of the key retrieval service. Required when using JWKS-based key rotation; omit for static key verification.

key-id-header

string

HTTP header containing the key ID used to select the correct key from the JWKS endpoint.

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 # 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

1 paths: 
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

1 navigation:
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

1 navigation:
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.

SDK signature verification

Configuration can be set at the document level (applies to all webhook endpoints) or per-endpoint (overrides the document-level default). Both levels accept the same configuration options.

Fern supports two verification methods: HMAC (symmetric key verification using shared secrets) and Asymmetric (public key verification using RSA, ECDSA, or Ed25519 keys).

Document-level

Per-endpoint override

openapi.yml

1 x-fern-webhook-signature:
2   type: hmac
3   header: x-webhook-signature
4   algorithm: sha256
5   encoding: hex
6 
7 paths:
8   /webhooks/payment:
9     post:
10       x-fern-webhook: true
11       # Inherits document-level signature config
12 
13   /webhooks/order:
14     post:
15       x-fern-webhook: true
16       # Inherits document-level signature config

Configuration options

Common fields

These fields apply to both HMAC and asymmetric verification.

type

'hmac' | 'asymmetric'Required

The signature verification method. Use hmac for symmetric key verification with shared secrets, or asymmetric for public key verification.

stringRequired

The HTTP header containing the signature. For example, x-webhook-signature or x-hub-signature-256.

encoding

'base64' | 'hex'Required

The encoding format of the signature value in the header.

signature-prefix

string

A prefix to strip from the signature header value before verification. For example, "sha256=" or "rsa=".

timestamp.header

stringRequired

HTTP header containing the delivery timestamp.

timestamp.format

'unix-seconds' | 'unix-millis' | 'iso8601'Required

Format of the timestamp value in the header.

timestamp.tolerance

integerDefaults to 300

Allowed clock skew in seconds. Requests with timestamps outside this window are rejected.

HMAC fields

These fields apply when type is set to hmac.

algorithm

'sha256' | 'sha1' | 'sha384' | 'sha512'Required

The HMAC hash algorithm for signature computation. sha256 is recommended. sha1 is deprecated and should only be used for legacy compatibility.

payload-format.components

list of stringsRequired

Ordered list of payload components to concatenate before hashing. Available components:

Component	Description
`body`	Raw request body
`timestamp`	Timestamp value from timestamp header
`notification-url`	The webhook/callback URL
`message-id`	Provider-assigned message identifier

payload-format.delimiter

stringRequired

String used to join the components. Use "." for timestamp-prefixed payloads or "" for direct concatenation.

Asymmetric fields

These fields apply when type is set to asymmetric.

asymmetric-algorithm

The asymmetric signing algorithm. rsa-sha256 and ecdsa-sha256 are widely supported defaults. ed25519 is a modern, efficient option.

jwks-url

string

JSON Web Key Set (JWKS) endpoint URL of the key retrieval service. Required when using JWKS-based key rotation; omit for static key verification.

key-id-header

string

HTTP header containing the key ID used to select the correct key from the JWKS endpoint.

1	webhooks:
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

1	paths:
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"

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

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

1	x-fern-webhook-signature:
2	type: hmac
3	header: x-webhook-signature
4	algorithm: sha256
5	encoding: hex
6
7	paths:
8	/webhooks/payment:
9	post:
10	x-fern-webhook: true
11	# Inherits document-level signature config
12
13	/webhooks/order:
14	post:
15	x-fern-webhook: true
16	# Inherits document-level signature config