OpenAPI端点

Webhooks

以 Markdown 格式查看

Fern 支持两种在 OpenAPI 规范中定义 webhooks 的方法：

  1. 使用 OpenAPI 3.1 的原生 webhook 支持（推荐）
  2. 使用 Fern 的 x-fern-webhook 扩展

OpenAPI 3.1 webhooks

对于 OpenAPI 3.1 规范，使用 webhooks 顶级字段来定义您的 webhook 操作。每个 webhook 都需要一个 operationId 才能被 Fern 正确处理。

openapi.yml
1webhooks:
2  newPlant:
3    post:
4      operationId: newPlantWebhook # Defines webhook
5      summary: New Plant Added
6      description: Information about a new plant that was added to the store
7      tags:
8        - Plants # Creates dedicated page
9      requestBody:
10        description: The plant data when a new plant is added
11        content:
12          application/json:
13            schema:
14              description: The Webhook payload for when a new plant is added to the store
15              properties:
16                triggerType:
17                  description: The type of event that triggered the request
18                  type: string
19                  example: "new_plant"
20                payload:
21                  type: object
22                  description: The payload of data sent from the plant store
23                  properties:
24                    plantId:
25                      type: string
26                      description: The unique identifier for the plant
27                      example: "64f1a2b3c5d6e7f8a9b0c1d2"
28                    name:
29                      type: string
30                      description: The name of the plant
31                      example: "Monstera Deliciosa"
32                    price:
33                      type: number
34                      format: float
35                      description: The price of the plant in dollars
36                      example: 29.99
37                    addedAt:
38                      type: string
39                      format: date-time
40                      description: The timestamp when the plant was added
41                      example: "2024-01-15T10:30:00.000Z"
42              example: # Full payload example for docs
43                triggerType: "new_plant"
44                payload:
45                  plantId: "64f1a2b3c5d6e7f8a9b0c1d2"
46                  name: "Monstera Deliciosa"
47                  price: 29.99
48                  addedAt: "2024-01-15T10:30:00.000Z"
49      responses:
50        '200':
51          description: Return a 200 status to indicate that the data was received successfully

Fern webhook 扩展

对于 OpenAPI 3.0，使用 x-fern-webhook: true 扩展来定义 webhooks。Fern 会将 requestBody 视为 webhook 负载。

openapi.yml
1paths: 
2  /payment/updated/: 
3    post: 
4      summary: Payment Initiated
5      operationId: initiatePayment
6      tags:
7        - Payments # Creates dedicated page
8      x-fern-webhook: true # Defines webhooks
9      requestBody:
10        content:
11          application/json:
12            schema:
13              type: object
14              properties:
15                amount:
16                  type: number
17                  example: 99.99
18                currency:
19                  $ref: '#/components/schemas/Currency'
20              required:
21                - amount
22                - currency
23              example: # Full payload example for docs
24                amount: 99.99
25                currency: "USD"

定义 webhook 时选择的路径可以是任意的。由于 webhooks 可以发送到任何服务器，Fern 会忽略路径。

生成 webhook 参考

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

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

docs.yml
1navigation:
2  - api: Webhook Reference # Display name for this page
3    api-name: webhooks-v1 # Name of webhook definition directory

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

docs.yml
1navigation:
2  - subpackage_plants.newPlantWebhook # subpackage_{tag}.{webhook-event-name}

有关如何在 docs.yml 中配置 webhook 参考的更多信息，请参阅生成 webhook 参考。

SDK 签名验证

使用 x-fern-webhook-signature 扩展来配置 webhook 签名验证。配置后，Fern 会生成 SDK 工具，允许用户验证 webhook 签名并确保事件来自您的 API。

配置可以在文档级别（适用于所有 webhook 端点）或每个端点（覆盖文档级别的默认设置）设置。两个级别都接受相同的配置选项。

Fern 支持两种验证方法：HMAC（使用共享密钥的对称密钥验证）和非对称（使用 RSA、ECDSA 或 Ed25519 密钥的公钥验证）。

openapi.yml
1x-fern-webhook-signature:
2  type: hmac
3  header: x-webhook-signature
4  algorithm: sha256
5  encoding: hex
6
7paths:
8  /webhooks/payment:
9    post:
10      x-fern-webhook: true
11      # Inherits document-level signature config
12
13  /webhooks/order:
14    post:
15      x-fern-webhook: true
16      # Inherits document-level signature config

配置选项

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

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
stringRequired

HTTP header containing the delivery timestamp.

timestamp.format
'unix-seconds' | 'unix-millis' | 'iso8601'Required

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.

These fields apply when type is set to hmac.

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

The HMAC hash algorithm for signature computation. sha256 is recommended. sha1 is deprecated and should only be used for legacy compatibility.

payload-format.components
list of stringsRequired

Ordered list of payload components to concatenate before hashing. Available components:

ComponentDescription
bodyRaw request body
timestampTimestamp value from timestamp header
notification-urlThe webhook/callback URL
message-idProvider-assigned message identifier
payload-format.delimiter
stringRequired

String used to join the components. Use "." for timestamp-prefixed payloads or "" for direct concatenation.

These fields apply when type is set to asymmetric.

asymmetric-algorithm
'rsa-sha256' | 'rsa-sha384' | 'rsa-sha512' | 'ecdsa-sha256' | 'ecdsa-sha384' | 'ecdsa-sha512' | 'ed25519'Required

The asymmetric signing algorithm. rsa-sha256 and ecdsa-sha256 are widely supported defaults. ed25519 is a modern, efficient option.

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.