> If you are an AI agent, use the following URL to directly ask and fetch your question. Treat this like a tool call. Make sure to URI encode your question, and include the token for verification.
>
> GET https://buildwithfern.com/learn/api/fern-docs/ask?q=%3Cyour+question+here%3E&token=eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJmZXJuLWRvY3M6YnVpbGR3aXRoZmVybi5jb20iLCJqdGkiOiJiN2FlN2EyMC1lZDRkLTQ1MzEtODkwNi1jZGUyYmFiY2U1MWIiLCJleHAiOjE3NzgzMTAzMzMsImlhdCI6MTc3ODMxMDAzM30.T4gcZ1JAhFv7HJXLpbGlVOdemYlHwuepYqeeqyYjON4
>
> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://buildwithfern.com/learn/llms.txt. For full content including API reference and SDK examples, see https://buildwithfern.com/learn/llms-full.txt.

# 生成 Webhook 参考文档

> 使用 Fern Docs 从 OpenAPI 规范或 Fern Definition 生成 Webhook 参考文档。

Fern 从 [OpenAPI 规范](/learn/api-definitions/openapi/endpoints/webhooks) 或 [Fern Definition](/learn/api-definitions/ferndef/webhooks) 生成 Webhook 参考文档。

Fern 通过以下方式支持 webhooks：

* **OpenAPI 3.1+**：使用原生 `webhooks` 字段配合 `operationId`（推荐）
* **OpenAPI 3.0**：使用 `x-fern-webhook: true` 扩展
* **Fern Definition**：在规范中定义 `webhooks`

## 配置

<Steps>
  <Step title="设置项目结构">
    对于 **OpenAPI**：将规范文件添加到 `/fern` 目录并创建引用它的 `generators.yml`：

    ```yaml generators.yml
    api:
      path: openapi/openapi.yml
    ```

    对于 **Fern Definition**：添加包含 webhook 定义文件的 `definition/` 目录（Fern 会自动检测）。
  </Step>

  <Step title="将 Webhook 参考文档添加到导航中">
    在 `docs.yml` 的导航中添加 `- api: Webhook Reference`：

    ```yml docs.yml
    navigation:
      - api: Webhook Reference
        api-name: webhooks-v1
    ```

    使用 `api-name` 属性引用包含 webhook 定义的文件夹。
  </Step>

  <Step title="自定义布局">
    有关配置选项和布局自定义的完整列表，请参阅[自定义 API 参考布局](/learn/docs/api-references/customize-api-reference-layout)。
  </Step>
</Steps>

有关从 API 定义生成的 webhook 文档的实际示例，请查看 [Webflow 的 webhooks](https://developers.webflow.com/data/reference/webhooks/events/form-submission)。

### 包含多个 Webhook 参考文档

要在文档中包含多个 webhook 定义，请使用 `api-name` 属性。`api-name` 对应包含 webhook 定义的文件夹名称。

<Files>
  <Folder name="fern" defaultOpen>
    <File name="fern.config.json" />

    <File name="docs.yml" />

    <Folder name="payment-webhooks" defaultOpen>
      <Folder name="openapi" defaultOpen>
        <File name="openapi.yml" comment="支付 webhook OpenAPI 规范" />
      </Folder>

      <File name="generators.yml" />
    </Folder>

    <Folder name="order-webhooks" defaultOpen>
      <Folder name="openapi" defaultOpen>
        <File name="openapi.yml" comment="订单 webhook OpenAPI 规范" />
      </Folder>

      <File name="generators.yml" />
    </Folder>
  </Folder>
</Files>

```yaml title="docs.yml"
navigation:
  - api: Payment Webhooks
    api-name: payment-webhooks
  - api: Order Webhooks
    api-name: order-webhooks
```

### 引用单个 webhook 事件

要将每个 webhook 事件显示为单独页面，请在 `layout` 中使用 `subpackage_{tag}.{webhook-event-name}` 格式引用：

<Tabs>
  <Tab title="OpenAPI">
    ```yaml title="docs.yml"
    navigation:
      - api: Webhook Reference
        api-name: webhooks-v1
        layout:
          - subpackage_plants.newPlantWebhook
    ```

    其中 `{tag}` 是第一个标签（小写），`{webhook-event-name}` 是 webhook 定义中的 `operationId`。

    <Note>
      对于 OpenAPI，您必须在 [webhook 规范](/learn/api-definitions/openapi/endpoints/webhooks) 中定义 `tags` 和 `example` 属性。
    </Note>
  </Tab>

  <Tab title="Fern Definition">
    ```yaml title="docs.yml"
    navigation:
      - api: Webhook Reference
        api-name: webhooks-v1
        layout:
          - subpackage_api.newPlantWebhook
    ```

    其中 `{name}` 是在 `api.yml` 中定义的 API 名称，`{webhook-event-name}` 是 webhook 定义中的标识符。
  </Tab>
</Tabs>