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

# Отправка вебхуков в вашу систему

> Интеграция «Вебхуки» отправляет подписанное JSON-событие на ваш эндпоинт, когда Foliant создаёт документ или завершает экспорт.

Интеграция **Вебхуки** предназначена для разработчиков. Она отправляет JSON-событие на выбранный вами HTTPS-адрес каждый раз, когда в Foliant что-то происходит. Так ваша система может на это отреагировать: например, сохранить PDF каждого счёта или забрать готовый экспорт.

Вебхуки находятся в бета-версии. Если вы не видите их в разделе **Настройки › Интеграции**, они пока недоступны для вашего магазина. Чтобы узнать о доступе, обратитесь в поддержку.

## События

| Событие | Когда отправляется |
| - | - |
| `document.generated` (**Документ создан**) | Foliant создаёт документ для заказа: при скачивании, экспорте или отправке PDF по электронной почте. |
| `export.completed` (**Экспорт завершён**) | Массовый экспорт готов. |

## Подключение вебхуков

1. В Foliant перейдите в раздел **Настройки › Интеграции**.

2. В карточке **Вебхуки** нажмите **Подключить**.

3. Заполните настройки:

   | Поле | Что указать |
   | - | - |
   | **URL эндпоинта** | Адрес, на который Foliant отправляет события. Он должен использовать HTTPS, например `https://example.com/webhooks/foliant`. |
   | **Секрет подписи** | Необязательно. Если указан секрет, каждый запрос подписывается, и вы можете проверить, что он пришёл от Foliant. |
   | **События** | События для отправки. По умолчанию выбраны оба. |

4. Нажмите **Подключить**.

Позже вы можете изменить URL, секрет и события в разделе **Настройки** на странице интеграции.

## Что содержит каждый запрос

Foliant отправляет запрос `POST` с телом в формате 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": { }
}
```

### Данные `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=` и затем подпись. Только если вы указали секрет подписи. |

## Проверка подписи

Подпись — это HMAC-SHA256 в шестнадцатеричном виде от метки времени, точки и исходного тела запроса (`<timestamp>.<body>`), где ключом служит ваш секрет подписи. Вычислите её на своей стороне и сравните со значением после `sha256=` в `X-Foliant-Signature`. Используйте исходное тело точно в том виде, в каком оно получено.

## Ответы и повторные попытки

* Любой ответ 2xx считается успешной доставкой.
* Если ваш эндпоинт возвращает ошибку 5xx, 408 или 429 либо не отвечает в течение 10 секунд, Foliant повторяет попытку позже, каждый раз ожидая дольше, — всего до 5 попыток.
* Другие ответы 4xx окончательны: Foliant не повторяет их.
* Каждое событие доставляется один раз для каждого документа или экспорта. После успешной доставки повторные попытки не отправляют его снова.

Каждая доставка отображается в разделе **Активность** на странице интеграции, где вы можете нажать **Повторить** для неудачной доставки. См. [Активность интеграции](https://foliant-help.iforiti.com/ru/integrations/integration-activity.md).

## Похожие статьи

* [Подключение интеграции и управление ею](https://foliant-help.iforiti.com/ru/integrations/connect-an-integration.md)
* [Активность интеграции](https://foliant-help.iforiti.com/ru/integrations/integration-activity.md)
* [Автоматизация с помощью Shopify Flow](https://foliant-help.iforiti.com/ru/integrations/shopify-flow.md)
* [Экспорт PDF](https://foliant-help.iforiti.com/ru/exports/export-pdfs.md)


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