Webhooks in the Fern Definition | Fern Documentation

Fern Definition isn’t recommended for new customers and Fern isn’t accepting feature requests for this format. It remains supported for existing users.

In Fern, you can specify webhooks in your API definition. The webhooks will be included in both the generated SDKs and the API documentation.

Webhook definition

Each webhook defines:

Method: The HTTP Method that the webhook will use (either GET or POST)
Headers: The headers that the webhook will send
Payload: The schema of the webhook payload

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

Inlined payloads

You can inline the schema of the payload by doing the following:

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

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

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

Or you can configure individual documentation pages per webhook event:

docs.yml

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

For more information on how to configure your webhook reference in docs.yml, see Generate your webhook reference.

SDK signature verification

Enterprise feature for SDKs

Using this feature in generated SDKs requires the Enterprise plan. To get started, reach out to support@buildwithfern.com.

You can configure webhook signature verification directly in your Fern Definition using the webhook-signature block. 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 webhooks) or per-webhook (overrides the document-level default). Both levels accept the same configuration options. To declare one scheme for the whole API, or when the definition models no webhooks, set api.settings.webhook-signature in generators.yml instead.

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-webhook override

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

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'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.