Fern DefinitionAdvanced

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
webhooks.yml
1webhooks: 
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
12types: 
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:

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

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

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