Fern 定义中的 Webhooks | Fern Documentation

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

Webhook 定义

每个 webhook 定义以下内容：

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

webhooks.yml

webhooks: 
  paymentNotification: 
    display-name: Payment Notification
    docs: Receive a notification when a payment changes status
    method: POST 
    headers: 
      X-Signature-Primary: 
        type: string 
        docs: An HMAC signature of the payload
    payload: PaymentNotificationPayload
types: 
  PaymentNotificationPayload: 
    discriminant: notificationType
    union: 
      queued: QueuedPaymentNotification
      processing: ProcessingPaymentNotification
      completed: CompletedPaymentNotification

内联负载

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

webhooks.yml

webhooks: 
  paymentNotification: 
    display-name: Payment Notification
    docs: Receive a notification when a payment changes status
    method: POST 
    headers: 
      X-Signature-Primary: 
        type: string 
        docs: An HMAC signature of the payload
    payload:
      name: PaymentNotificationPayload
      properties: 
        id:
          type: string
          docs: The notification id
        amount: double
        currency: Currency

生成 webhook 参考

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

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

docs.yml

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

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

docs.yml

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

webhook-signature:
  type: hmac
  header: x-webhook-signature
  algorithm: sha256
  encoding: hex
webhooks:
  userCreated:
    method: POST
    payload: UserCreatedPayload
    # Inherits document-level signature config
  orderCompleted:
    method: POST
    payload: OrderCompletedPayload
    # 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'Defaults to base64

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

string

HTTP header containing the delivery timestamp. Required when timestamp is configured.

timestamp.format

'unix-seconds' | 'unix-millis' | 'iso8601'Defaults to unix-seconds

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'Defaults to sha256

The HMAC hash algorithm for signature computation. sha256 is recommended. sha1 is deprecated and should only be used for legacy compatibility. When algorithm-header is set, this is the default used for requests that don’t carry the algorithm header.

algorithm-header.header

stringRequired

HTTP header that selects the HMAC algorithm per request, for providers that send the algorithm (and optionally a key ID) alongside each webhook instead of using one fixed algorithm. Generated SDKs add a request-level verifyRequest helper that reads this header.

algorithm-header is accepted in generators.yml under api.settings.webhook-signature and in a Fern Definition webhook-signature or webhook signature block. The OpenAPI x-fern-webhook-signature extension doesn’t support it yet.

webhook-signature:
  type: hmac
  header: X-Signature
  algorithm: sha1
  algorithm-header:
    header: X-Signature-Settings
    key-id-delimiter: ";"
    algorithms:
      HMAC_SHA1: sha1
      HMAC_SHA256: sha256

algorithm-header.key-id-delimiter

string

Separator between a key ID and the algorithm in the header value, which then takes the form <key-id><delimiter><algorithm> (for example, key_123;HMAC_SHA256). The value is split on the last occurrence of the delimiter, and the key ID is passed to the caller to resolve the matching signing secret. When omitted, the whole header value is the algorithm. When algorithm-parameter is set, this instead separates the <name>=<value> pairs and defaults to ,.

algorithm-header.key-id-parameter

string

Name of the parameter that carries the key ID when the header is a list of <name>=<value> pairs, such as key for Twilio’s key=webhooks_sharedkey_<id>,algorithm=HMAC_SHA256. Applies only when algorithm-parameter is also set. The parameter’s value is passed to the caller to resolve the matching signing secret, and a request whose header lacks it fails verification.

algorithm-header.algorithm-parameter

string

Name of the parameter that carries the algorithm when the header is a list of <name>=<value> pairs, such as algorithm. Setting it switches the header to named-parameter parsing: the value is split on key-id-delimiter (default ,), names and values are trimmed, and parts without = are ignored. The algorithm parameter’s value is then matched against algorithms.

algorithm-header:
  header: X-Twilio-Webhooks-Signature-Settings
  key-id-delimiter: ","
  key-id-parameter: key
  algorithm-parameter: algorithm
  algorithms:
    HMAC_SHA1: sha1
    HMAC_SHA256: sha256

algorithm-header.algorithms

map of string to 'sha256' | 'sha1' | 'sha384' | 'sha512'Required

Allowed header values mapped to the HMAC algorithm each one selects, such as HMAC_SHA256: sha256. Header values are matched exactly, and a request with a value not listed here fails verification. Requires at least one entry.

payload-format.components

list of strings

Ordered list of payload components to concatenate before hashing. When omitted, only the raw request body is signed. 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

string

String used to join the components. Use "." for timestamp-prefixed payloads or "" for direct concatenation. Required when payload-format.components is set.

body-hash-binding.algorithm

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

Hash algorithm applied to the raw request body. Independent of algorithm, which applies to the signature itself. Set body-hash-binding when the provider transmits a hash of the body alongside a signature computed over the notification URL.

body-hash-binding.encoding

'base64' | 'hex'Defaults to base64

Encoding of the transmitted body hash.

body-hash-binding.location.type

'query-parameter'Required

Where the body hash is transmitted. Query parameters on the notification URL are the only supported location.

body-hash-binding.location.name

stringRequired

Name of the query parameter carrying the body hash.

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.

payload-format.components

list of strings

Ordered list of payload components to concatenate before signing. When omitted, only the raw request body is signed. 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

Without timestamp in the components list, the timestamp.tolerance check can’t protect against replay attacks because the timestamp is unauthenticated. Include timestamp to ensure replay protection.

payload-format.delimiter

string

String used to join the components. Use "." for timestamp-prefixed payloads or "" for direct concatenation. Required when payload-format.components is set.

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.