> ## 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を送信する

> Webhooks連携は、Foliantが書類を生成したときやエクスポートが完了したときに、署名付きのJSONイベントを指定のエンドポイントに送信します。

**Webhooks**連携は開発者向けの機能です。Foliantで何かが起きるたびに、指定したHTTPSアドレスへJSONイベントを送信します。これにより、独自のシステムで対応できます。たとえば、請求書PDFを1件ずつ保管したり、完了したエクスポートを取得したりできます。

Webhooksはベータ版です。**設定 › 連携**に表示されない場合は、まだご利用のストアに提供されていません。利用についてはサポートにお問い合わせください。

## イベント

| イベント | 送信されるタイミング |
| - | - |
| `document.generated`（**書類の生成**） | Foliantが注文の書類を作成したとき（ダウンロード、エクスポート、PDF送付メール）。 |
| `export.completed`（**エクスポートの完了**） | 一括エクスポートの準備ができたとき。 |

## Webhooksを接続する

1. Foliantで**設定 › 連携**に移動します。

2. **Webhooks**で**接続**をクリックします。

3. 設定を入力します。

   | 項目 | 入力する内容 |
   | - | - |
   | **エンドポイントURL** | Foliantがイベントを送信するアドレスです。`https://example.com/webhooks/foliant`のように、HTTPSを使用する必要があります。 |
   | **署名シークレット** | 任意です。シークレットを設定すると、すべてのリクエストに署名が付き、Foliantからの送信であることを確認できます。 |
   | **イベント** | 送信するイベントです。初期設定では両方が選択されています。 |

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で計算した16進数の値です。受信側で計算し、`X-Foliant-Signature`の`sha256=`以降の値と比較してください。本文は受信したままの未加工のものを使用してください。

## レスポンスと再試行

* 2xxのレスポンスはすべて配信済みとみなされます。
* エンドポイントが5xxエラー、408、429を返した場合、または10秒以内に応答しない場合、Foliantはあとで再試行します。再試行のたびに待ち時間が長くなり、最大5回まで試行します。
* その他の4xxレスポンスは最終的な結果となり、Foliantは再試行しません。
* 各イベントは、書類またはエクスポートごとに1回配信されます。成功後に再試行で重複して送信されることはありません。

すべての配信は連携のページの**アクティビティ**に表示され、失敗した配信は**再試行**できます。詳しくは[連携のアクティビティ](https://foliant-help.iforiti.com/jp/integrations/integration-activity.md)をご覧ください。

## 関連記事

* [連携を接続・管理する](https://foliant-help.iforiti.com/jp/integrations/connect-an-integration.md)
* [連携のアクティビティ](https://foliant-help.iforiti.com/jp/integrations/integration-activity.md)
* [Shopify Flowで自動化する](https://foliant-help.iforiti.com/jp/integrations/shopify-flow.md)
* [PDFをエクスポートする](https://foliant-help.iforiti.com/jp/exports/export-pdfs.md)


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