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

# 자체 시스템으로 웹훅 보내기

> 웹훅 연동은 Foliant가 문서를 생성하거나 내보내기를 완료하면 서명된 JSON 이벤트를 자체 엔드포인트로 보냅니다.

**웹훅** 연동은 개발자를 위한 기능입니다. Foliant에서 어떤 일이 발생할 때마다 지정한 HTTPS 주소로 JSON 이벤트를 보내므로, 자체 시스템에서 이에 대응할 수 있습니다. 예를 들어 각 인보이스 PDF를 보관하거나 완료된 내보내기를 가져올 수 있습니다.

웹훅은 베타 버전입니다. **설정 › 연동**에 보이지 않는다면 아직 스토어에 제공되지 않는 것입니다. 이용을 원하시면 지원팀에 문의하세요.

## 이벤트

| 이벤트 | 전송 시점 |
| - | - |
| `document.generated` (**문서 생성됨**) | Foliant가 주문의 문서를 생성할 때: 다운로드, 내보내기 또는 PDF 발송 이메일. |
| `export.completed` (**내보내기 완료됨**) | 일괄 내보내기가 준비되었을 때. |

## 웹훅 연결하기

1. Foliant에서 **설정 › 연동**으로 이동합니다.

2. **웹훅**에서 **연결**을 클릭합니다.

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>`)을 서명 시크릿을 키로 사용하여 계산한 16진수 HMAC-SHA256 값입니다. 수신 측에서 직접 계산한 후 `X-Foliant-Signature`의 `sha256=` 뒤에 있는 값과 비교하세요. 원본 본문은 수신한 그대로 사용하세요.

## 응답 및 재시도

* 2xx 응답은 모두 전송 완료로 간주됩니다.
* 엔드포인트가 5xx 오류, 408 또는 429를 반환하거나 10초 이내에 응답하지 않으면 Foliant는 나중에 다시 시도합니다. 시도할 때마다 대기 시간이 길어지며 최대 5회까지 시도합니다.
* 그 외 4xx 응답은 최종 결과로 처리되며 Foliant는 재시도하지 않습니다.
* 각 이벤트는 문서 또는 내보내기당 한 번 전송됩니다. 전송에 성공한 후에는 재시도로 인해 중복 전송되지 않습니다.

모든 전송 내역은 연동 페이지의 **활동**에 표시되며, 실패한 전송은 여기에서 **다시 시도**할 수 있습니다. [연동 활동](https://foliant-help.iforiti.com/ko/integrations/integration-activity.md)을 참고하세요.

## 관련 문서

* [연동 연결 및 관리하기](https://foliant-help.iforiti.com/ko/integrations/connect-an-integration.md)
* [연동 활동](https://foliant-help.iforiti.com/ko/integrations/integration-activity.md)
* [Shopify Flow로 자동화하기](https://foliant-help.iforiti.com/ko/integrations/shopify-flow.md)
* [PDF 내보내기](https://foliant-help.iforiti.com/ko/exports/export-pdfs.md)


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