Webhooks in the Fern Definition | Fern Documentation

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

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:

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

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

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:

docs.yml

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 verification utilities

Fern automatically generates webhook signature verification utilities in your SDKs based on your webhook definitions. For more information, see Webhook signature verification.