> ## 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 中發生特定事件時，它會將 JSON 事件傳送到您選擇的 HTTPS 位址，讓您自己的系統做出回應，例如歸檔每份發票 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/zh-Hant/integrations/integration-activity.md)。

## 相關文章

* [連結及管理整合](https://foliant-help.iforiti.com/zh-Hant/integrations/connect-an-integration.md)
* [整合活動](https://foliant-help.iforiti.com/zh-Hant/integrations/integration-activity.md)
* [使用 Shopify Flow 自動化](https://foliant-help.iforiti.com/zh-Hant/integrations/shopify-flow.md)
* [匯出 PDF](https://foliant-help.iforiti.com/zh-Hant/exports/export-pdfs.md)


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