> ## 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.

# Gửi webhook đến hệ thống của bạn

> Tích hợp Webhooks gửi một sự kiện JSON có chữ ký đến endpoint của bạn khi Foliant tạo tài liệu hoặc hoàn tất một lượt xuất.

Tích hợp **Webhooks** dành cho nhà phát triển. Tích hợp này gửi một sự kiện JSON đến địa chỉ HTTPS bạn chọn mỗi khi có điều gì đó xảy ra trong Foliant, để hệ thống của bạn có thể phản hồi, ví dụ lưu trữ từng PDF hóa đơn hoặc lấy một lượt xuất đã hoàn tất.

Webhooks đang ở giai đoạn beta. Nếu bạn không thấy tích hợp này trong **Cài đặt › Tích hợp**, tức là tích hợp chưa được cung cấp cho cửa hàng của bạn. Hãy liên hệ bộ phận hỗ trợ để hỏi về quyền truy cập.

## Sự kiện

| Sự kiện | Được gửi khi |
| - | - |
| `document.generated` (**Document generated**) | Foliant tạo một tài liệu cho đơn hàng: một lượt tải xuống, một lượt xuất hoặc một email gửi PDF. |
| `export.completed` (**Export completed**) | Một lượt xuất hàng loạt đã sẵn sàng. |

## Kết nối webhook

1. Trong Foliant, vào **Cài đặt › Tích hợp**.

2. Trên **Webhooks**, nhấp vào **Kết nối**.

3. Điền các cài đặt:

   | Trường | Nội dung cần nhập |
   | - | - |
   | **Endpoint URL** | Địa chỉ Foliant gửi sự kiện đến. Địa chỉ phải dùng HTTPS, chẳng hạn `https://example.com/webhooks/foliant`. |
   | **Signing secret** | Không bắt buộc. Khi có secret, mọi yêu cầu đều được ký để bạn có thể kiểm tra yêu cầu đến từ Foliant. |
   | **Events** | Các sự kiện cần gửi. Theo mặc định, cả hai đều được chọn. |

4. Nhấp vào **Kết nối**.

Sau này, bạn có thể thay đổi URL, secret và sự kiện trong **Cài đặt** trên trang của tích hợp.

## Nội dung của mỗi yêu cầu

Foliant gửi một yêu cầu `POST` với phần thân JSON:

```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": { }
}
```

### Dữ liệu của `document.generated`

* `template`: `uuid` và `name` của mẫu.
* `document_type`: `invoice`, `credit_note`, `quote`, hoặc để trống với các tài liệu khác.
* `order`: `id`, `name` và `type` của đơn hàng (đơn hàng hoặc đơn hàng nháp).
* `refund_id` và `fulfillment_id`, khi tài liệu dành cho một khoản hoàn tiền hoặc một lần giao hàng.
* `document_number` và `issued_at`, với các tài liệu có đánh số.
* `source`: cách tài liệu được tạo, chẳng hạn `download`, `admin_download`, `export` hoặc `email`.
* `export`: ID của lượt xuất, khi tài liệu thuộc một lượt xuất.
* `generated_at`.

### Dữ liệu của `export.completed`

* `export`: `uuid`, `order_type`, `template_uuids`, số `orders`, `orders_skipped` (bị xóa sau khi được chọn) và `documents`, `requested_by` (`merchant` hoặc `customer`) và `completed_at` của lượt xuất.
* `download_url`: liên kết để tải lượt xuất xuống, và `download_url_expires_at`, thời điểm liên kết đó hết hiệu lực.
* `download_expires_at`: thời điểm bản thân lượt xuất hết hạn.

Sự kiện chứa ID và số lượng, không chứa địa chỉ email của khách hàng.

### Header

| Header | Nội dung |
| - | - |
| `X-Foliant-Event` | Sự kiện, chẳng hạn `document.generated`. |
| `X-Foliant-Delivery` | ID duy nhất của lần gửi (giống `id` trong phần thân). |
| `X-Foliant-Timestamp` | Thời điểm gửi, tính bằng giây Unix. |
| `X-Foliant-Signature` | `sha256=` theo sau là chữ ký. Chỉ có khi bạn đặt signing secret. |

## Kiểm tra chữ ký

Chữ ký là một HMAC-SHA256 dạng hex của timestamp, một dấu chấm và phần thân thô của yêu cầu (`<timestamp>.<body>`), dùng signing secret của bạn làm khóa. Hãy tính chữ ký ở phía bạn và so sánh với giá trị sau `sha256=` trong `X-Foliant-Signature`. Dùng phần thân thô đúng như khi nhận được.

## Phản hồi và gửi lại

* Mọi phản hồi 2xx đều được tính là đã gửi thành công.
* Nếu endpoint của bạn trả về lỗi 5xx, 408 hoặc 429, hoặc không phản hồi trong vòng 10 giây, Foliant sẽ thử lại sau, mỗi lần chờ lâu hơn, tối đa 5 lần.
* Các phản hồi 4xx khác là kết quả cuối cùng: Foliant không thử lại.
* Mỗi sự kiện được gửi một lần cho mỗi tài liệu hoặc lượt xuất. Sau khi gửi thành công, việc thử lại không bao giờ gửi sự kiện hai lần.

Mọi lần gửi đều hiển thị trong **Hoạt động** trên trang của tích hợp, nơi bạn có thể **Thử lại** một lần gửi thất bại. Xem [Hoạt động của tích hợp](https://foliant-help.iforiti.com/vi/integrations/integration-activity.md).

## Bài viết liên quan

* [Kết nối và quản lý tích hợp](https://foliant-help.iforiti.com/vi/integrations/connect-an-integration.md)
* [Hoạt động của tích hợp](https://foliant-help.iforiti.com/vi/integrations/integration-activity.md)
* [Tự động hóa với Shopify Flow](https://foliant-help.iforiti.com/vi/integrations/shopify-flow.md)
* [Xuất PDF](https://foliant-help.iforiti.com/vi/exports/export-pdfs.md)


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