Webhooks in the Fern Definition

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:

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

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

Inlined payloads

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

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

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:

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

Or you can configure individual documentation pages per webhook event:

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

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.

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

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

Configuration options