Fern 定义中的 Webhooks

在 Fern 中，您可以在 API 定义中指定 webhooks。Webhooks 将被包含在生成的 SDK 和 API 文档中。

Webhook 定义

每个 webhook 定义以下内容：

方法：webhook 将使用的 HTTP 方法（GET 或 POST）
标头：webhook 将发送的标头
负载：webhook 负载的模式

webhooks.yml

1 webhooks: 
2   paymentNotification: 
3     display-name: Payment Notification
4     docs: Receive a notification when a payment changes status
5     method: POST 
6     headers: 
7       X-Signature-Primary: 
8         type: string 
9         docs: An HMAC signature of the payload
10     payload: PaymentNotificationPayload
11 
12 types: 
13   PaymentNotificationPayload: 
14     discriminant: notificationType
15     union: 
16       queued: QueuedPaymentNotification
17       processing: ProcessingPaymentNotification
18       completed: CompletedPaymentNotification

内联负载

您可以通过以下方式内联负载的模式：

webhooks.yml

1 webhooks: 
2   paymentNotification: 
3     display-name: Payment Notification
4     docs: Receive a notification when a payment changes status
5     method: POST 
6     headers: 
7       X-Signature-Primary: 
8         type: string 
9         docs: An HMAC signature of the payload
10     payload:
11       name: PaymentNotificationPayload
12       properties: 
13         id:
14           type: string
15           docs: The notification id
16         amount: double
17         currency: Currency

生成 webhook 参考

Fern Docs 可以从您的定义自动生成 webhook 参考文档。在您的 docs.yml 文件中进行设置。

您的 webhook 参考可以是单个文档页面：

docs.yml

1 navigation:
2   - api: Webhook Reference # Display name for this page
3     api-name: webhooks-v1 # Directory containing webhook definition

或者您可以为每个 webhook 事件配置单独的文档页面：

docs.yml

1 navigation:
2   - subpackage_api.newPlantWebhook # Format: subpackage_{name-of-api}.{webhook-event-name}

有关如何在 docs.yml 中配置 webhook 参考的更多信息，请参阅生成您的 webhook 参考。

SDK 签名验证

您可以使用 webhook-signature 块直接在 Fern 定义中配置 webhook 签名验证。配置后，Fern 会生成 SDK 实用工具，允许用户验证 webhook 签名并确保事件来自您的 API。

配置可以在文档级别（适用于所有 webhooks）或每个 webhook（覆盖文档级别的默认值）设置。两个级别都接受相同的配置选项。

Fern 支持两种验证方法：HMAC（使用共享密钥的对称密钥验证）和非对称（使用 RSA、ECDSA 或 Ed25519 密钥的公钥验证）。

文档级别

每个 webhook 覆盖

api.yml

1 webhook-signature:
2   type: hmac
3   header: x-webhook-signature
4   algorithm: sha256
5   encoding: hex
6 
7 webhooks:
8   userCreated:
9     method: POST
10     payload: UserCreatedPayload
11     # Inherits document-level signature config
12 
13   orderCompleted:
14     method: POST
15     payload: OrderCompletedPayload
16     # Inherits document-level signature config

配置选项

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 中，您可以在 API 定义中指定 webhooks。Webhooks 将被包含在生成的 SDK 和 API 文档中。

Webhook 定义

每个 webhook 定义以下内容：

方法：webhook 将使用的 HTTP 方法（GET 或 POST）
标头：webhook 将发送的标头
负载：webhook 负载的模式

webhooks.yml

1 webhooks: 
2   paymentNotification: 
3     display-name: Payment Notification
4     docs: Receive a notification when a payment changes status
5     method: POST 
6     headers: 
7       X-Signature-Primary: 
8         type: string 
9         docs: An HMAC signature of the payload
10     payload: PaymentNotificationPayload
11 
12 types: 
13   PaymentNotificationPayload: 
14     discriminant: notificationType
15     union: 
16       queued: QueuedPaymentNotification
17       processing: ProcessingPaymentNotification
18       completed: CompletedPaymentNotification

内联负载

您可以通过以下方式内联负载的模式：

webhooks.yml

1 webhooks: 
2   paymentNotification: 
3     display-name: Payment Notification
4     docs: Receive a notification when a payment changes status
5     method: POST 
6     headers: 
7       X-Signature-Primary: 
8         type: string 
9         docs: An HMAC signature of the payload
10     payload:
11       name: PaymentNotificationPayload
12       properties: 
13         id:
14           type: string
15           docs: The notification id
16         amount: double
17         currency: Currency

生成 webhook 参考

Fern Docs 可以从您的定义自动生成 webhook 参考文档。在您的 docs.yml 文件中进行设置。

您的 webhook 参考可以是单个文档页面：

docs.yml

1 navigation:
2   - api: Webhook Reference # Display name for this page
3     api-name: webhooks-v1 # Directory containing webhook definition

或者您可以为每个 webhook 事件配置单独的文档页面：

docs.yml

1 navigation:
2   - subpackage_api.newPlantWebhook # Format: subpackage_{name-of-api}.{webhook-event-name}

有关如何在 docs.yml 中配置 webhook 参考的更多信息，请参阅生成您的 webhook 参考。

SDK 签名验证

配置可以在文档级别（适用于所有 webhooks）或每个 webhook（覆盖文档级别的默认值）设置。两个级别都接受相同的配置选项。

Fern 支持两种验证方法：HMAC（使用共享密钥的对称密钥验证）和非对称（使用 RSA、ECDSA 或 Ed25519 密钥的公钥验证）。

文档级别

每个 webhook 覆盖

api.yml

1 webhook-signature:
2   type: hmac
3   header: x-webhook-signature
4   algorithm: sha256
5   encoding: hex
6 
7 webhooks:
8   userCreated:
9     method: POST
10     payload: UserCreatedPayload
11     # Inherits document-level signature config
12 
13   orderCompleted:
14     method: POST
15     payload: OrderCompletedPayload
16     # Inherits document-level signature config

配置选项

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	paymentNotification:
3	display-name: Payment Notification
4	docs: Receive a notification when a payment changes status
5	method: POST
6	headers:
7	X-Signature-Primary:
8	type: string
9	docs: An HMAC signature of the payload
10	payload: PaymentNotificationPayload
11
12	types:
13	PaymentNotificationPayload:
14	discriminant: notificationType
15	union:
16	queued: QueuedPaymentNotification
17	processing: ProcessingPaymentNotification
18	completed: CompletedPaymentNotification

1	navigation:
2	- api: Webhook Reference # Display name for this page
3	api-name: webhooks-v1 # Directory containing webhook definition

1	navigation:
2	- subpackage_api.newPlantWebhook # Format: subpackage_{name-of-api}.{webhook-event-name}

1	webhook-signature:
2	type: hmac
3	header: x-webhook-signature
4	algorithm: sha256
5	encoding: hex
6
7	webhooks:
8	userCreated:
9	method: POST
10	payload: UserCreatedPayload
11	# Inherits document-level signature config
12
13	orderCompleted:
14	method: POST
15	payload: OrderCompletedPayload
16	# Inherits document-level signature config