> ## Documentation Index
> Fetch the complete documentation index at: https://foliant-help.iforiti.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 向您自己的系统发送 Webhook

> 当 Foliant 生成文档或完成导出时，Webhooks 集成会向您自己的端点发送一个已签名的 JSON 事件。

**Webhooks** 集成面向开发者。每当 Foliant 中发生某件事时，它会向您选择的 HTTPS 地址发送一个 JSON 事件，让您自己的系统作出响应，例如归档每张发票 PDF，或获取已完成的导出。

Webhooks 目前处于测试阶段。如果您在 **设置 › 集成** 中看不到它，说明您的商店暂时还无法使用。请联系支持团队咨询开通事宜。

## 事件

| 事件 | 发送时机 |
| - | - |
| `document.generated`（**Document generated**） | Foliant 为订单创建文档时：下载、导出或 PDF 发送邮件。 |
| `export.completed`（**Export completed**） | 批量导出已就绪时。 |

## 连接 Webhooks

1. 在 Foliant 中，前往 **设置 › 集成**。

2. 在 **Webhooks** 上，点击 **连接**。

3. 填写设置：

   | 字段 | 填写内容 |
   | - | - |
   | **Endpoint URL** | Foliant 发送事件的地址。必须使用 HTTPS，例如 `https://example.com/webhooks/foliant`。 |
   | **Signing secret** | 可选。设置密钥后，每个请求都会被签名，方便您确认请求来自 Foliant。 |
   | **Events** | 要发送的事件。默认两个都已选中。 |

4. 点击 **连接**。

之后，您可以在该集成页面的 **设置** 中更改 URL、密钥和事件。

## 每个请求包含的内容

Foliant 会发送一个带 JSON 正文的 `POST` 请求：

```json theme={null}
{
  "id": "a unique delivery id",
  "event": "document.generated",
  "created_at": "2026-10-11T09:30:00+00:00",
  "shop": "your-store.myshopify.com",
  "data": { }
}
```

### `document.generated` 数据

* `template`：模板的 `uuid` 和 `name`。
* `document_type`：`invoice`、`credit_note`、`quote`，其他文档则为空。
* `order`：订单的 `id`、`name` 和 `type`（订单或草稿订单）。
* `refund_id` 和 `fulfillment_id`：当文档用于退款或发货时提供。
* `document_number` 和 `issued_at`：用于带编号的文档。
* `source`：文档的生成方式，例如 `download`、`admin_download`、`export` 或 `email`。
* `export`：导出的 ID，当文档属于某次导出时提供。
* `generated_at`。

### `export.completed` 数据

* `export`：导出的 `uuid`、`order_type`、`template_uuids`、`orders` 数量、`orders_skipped`（选中后被删除的订单）和 `documents`、`requested_by`（`merchant` 或 `customer`）以及 `completed_at`。
* `download_url`：导出的下载链接；`download_url_expires_at`：该链接失效的时间。
* `download_expires_at`：导出本身过期的时间。

事件只包含 ID 和数量，不包含客户的电子邮件地址。

### 请求头

| 请求头 | 内容 |
| - | - |
| `X-Foliant-Event` | 事件，例如 `document.generated`。 |
| `X-Foliant-Delivery` | 本次发送的唯一 ID（与正文中的 `id` 相同）。 |
| `X-Foliant-Timestamp` | 发送时间，以 Unix 秒表示。 |
| `X-Foliant-Signature` | `sha256=` 后跟签名。仅在您设置了签名密钥时提供。 |

## 验证签名

签名是对时间戳、一个英文句点和原始请求正文（`<timestamp>.<body>`）计算的十六进制 HMAC-SHA256，密钥为您的签名密钥。请在您这边计算签名，并与 `X-Foliant-Signature` 中 `sha256=` 之后的值进行比较。请使用与收到时完全一致的原始正文。

## 响应与重试

* 任何 2xx 响应都视为已送达。
* 如果您的端点返回 5xx 错误、408 或 429，或在 10 秒内未响应，Foliant 会稍后重试，每次等待的时间更长，最多尝试 5 次。
* 其他 4xx 响应为最终结果：Foliant 不会重试。
* 每个事件针对每个文档或导出只送达一次。成功后，重试绝不会重复发送。

每次发送都会显示在该集成页面的 **活动** 中，您可以在那里对失败的发送点击 **重试**。请参阅[集成活动](https://foliant-help.iforiti.com/cn/integrations/integration-activity.md)。

## 相关文章

* [连接和管理集成](https://foliant-help.iforiti.com/cn/integrations/connect-an-integration.md)
* [集成活动](https://foliant-help.iforiti.com/cn/integrations/integration-activity.md)
* [使用 Shopify Flow 实现自动化](https://foliant-help.iforiti.com/cn/integrations/shopify-flow.md)
* [导出 PDF](https://foliant-help.iforiti.com/cn/exports/export-pdfs.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.