> For the complete documentation index, see [llms.txt](https://api-kit.prix.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-kit.prix.im/webhook.md).

# 웹훅 이용하기

프릭스에서 제공하는 웹훅 이벤트 목록입니다.

프릭스에서 제공하는 웹훅 이벤트 목록입니다.

워크스페이스 내 "설정 메뉴 > 웹훅 관리"에서 웹훅을 관리할 수 있습니다.

* 직접 원하는 이벤트에 맞게 웹훅을 추가할 수 있습니다.
* 원하는 계약 태그를 선택하여 해당 태그가 붙은 계약서 이벤트에만 웹훅을 발송할 수 있습니다. (태그 필터 미등록 시 모든 이벤트 발송)
* 웹훅 로그 목록을 확인할 수 있습니다.

<br>

## 웹훅 태그 필터

**계약서 이벤트**( 계약서 생성, 전자서명 요청/체결/참여/만료 이벤트)에 대해 특정 계약 태그를 선택하여 웹훅을 등록할 수 있습니다.

### 태그 필터의 동작 방식

* **태그 미등록**: 웹훅이 모든 계약서 이벤트를 수신합니다.
* **태그 등록**: 해당 태그가 붙은 계약서 이벤트에만 웹훅이 발송됩니다.
* **다중 태그 등록**: 등록된 태그 중 **하나 이상**이 계약서에 붙어있으면 웹훅이 발송됩니다

### 태그 필터 제약사항

* **영업문서 이벤트**(`DOCUMENT_*`)와 태그 필터는 함께 사용할 수 없습니다.
  * 영업문서에는 태그가 없기 때문에, 웹훅 UI에서 영업문서 이벤트를 선택하면 태그 입력 필드가 자동으로 숨겨집니다.
  * 계약서 이벤트와 영업문서 이벤트를 함께 선택한 경우, 혼합된 상태에서도 태그 필터링이 불가능합니다.
* **전자서명 템플릿 삭제 이벤트**(`SIGNATURE_TEMPLATE_DELETED`)는 계약서 태그 필터 대상이 아닙니다.
  * 해당 이벤트를 구독한 웹훅에는 태그 설정과 상관없이 이벤트가 발송됩니다.

<br>

## (1) 웹훅 이벤트 타입

웹훅으로 등록할 수 있는 이벤트 타입은 아래와 같습니다.

| 이벤트 타입                       | 설명                                                         | 카테고리     |
| ---------------------------- | ---------------------------------------------------------- | -------- |
| CONTRACT\_CREATED            | 계약서 등록 이벤트입니다.                                             | 계약서      |
| SIGNATURE\_CREATED           | 전자서명 생성 이벤트입니다.                                            | 전자서명     |
| SIGNATURE\_CONCLUDED         | 모든 참여자가 서명을 완료하여 계약이 체결되는 이벤트입니다.                          | 전자서명     |
| SIGNATURE\_PARTICIPATED      | 개별 전자서명 참여자의 서명 완료 이벤트입니다.                                 | 전자서명     |
| SIGNATURE\_EXPIRED           | 전자서명이 체결되지 않고 만료된 경우, 만료일 다음날 오전 11시에 호출되는 전자서명 만료 이벤트입니다. | 전자서명     |
| SIGNATURE\_TEMPLATE\_DELETED | 전자서명 템플릿이 삭제되는 이벤트입니다.                                     | 전자서명 템플릿 |
| DOCUMENT\_CREATED            | 영업문서 생성 완료 이벤트입니다.                                         | 영업문서     |

<br>

## (2) 계약서 카테고리 웹훅 이벤트 본문

계약서 카테고리의 웹훅 요청의 Body 예시입니다.

```json
{
  "eventType": "CONTRACT_CREATED",
  "createdAt": "2024-11-15T00:00:00.000Z",
  "contract": {
    "uuid": "ed976505-bcbd-47bd-913d-f4cde05dea7a", // 문서 식별값 (uuid 값을 api에서 사용)
    "title": "A컴퍼니 MOU", // 계약서 이름
    "status": "CREATED", // 계약 상태 (CREATED, CONCLUDED)
    "createdAt": "2024-11-15T00:00:00.000Z",
    "tagIds": [1, 3], // 계약서에 붙은 태그 ID 목록 (태그 필터 등록 시에만 포함)
    "tagNames": ["production", "important"] // 계약서에 붙은 태그 이름 목록 (태그 필터 등록 시에만 포함)
  }
}
```

> **참고**: `tagIds`와 `tagNames`는 웹훅 등록 시 태그를 선택한 경우에만 payload에 포함됩니다.

<br>

## (3) 전자서명 카테고리 웹훅 이벤트 본문

전자서명 카테고리의 웹훅 요청의 Body 예시입니다.

```json
{
  "eventType": "SIGNATURE_CREATED",
  "createdAt": "2024-11-15T00:00:00.000Z",
  "contract": {
    "uuid": "ed976505-bcbd-47bd-913d-f4cde05dea7a", // 문서 식별값 (uuid 값을 api에서 사용)
    "title": "A컴퍼니 MOU", // 계약서 이름
    "status": "CREATED", // 계약 상태 (CREATED, CONCLUDED)
    "createdAt": "2024-11-01T00:00:00.000Z",
    "tagIds": [1, 3], // 계약서에 붙은 태그 ID 목록 (태그 필터 등록 시에만 포함)
    "tagNames": ["production", "important"] // 계약서에 붙은 태그 이름 목록 (태그 필터 등록 시에만 포함)
  },
  "signature": {
    "uuid": "57139f5c-37d0-4c30-bdb6-ef6106040756", // 전자서명 식별자
    "title": "A컴퍼니 MOU 서명 요청", // 전자서명 이름
    "status": "WAITING", // 상태 (WAITING, DONE, CANCELED / WAITING은 서명 요청 후 대기 상태를 의미)
    "createdAt": "2024-11-15T00:00:00.000Z"
  }
}
```

<br>

## (4) 전자서명 템플릿 카테고리 웹훅 이벤트 본문

전자서명 템플릿 카테고리의 웹훅 요청의 Body 예시입니다.

```json
{
  "eventType": "SIGNATURE_TEMPLATE_DELETED",
  "createdAt": "2024-11-15T00:00:00.000Z",
  "signatureTemplate": {
    "id": 4328, // 전자서명 템플릿 식별값
    "name": "MOU 템플릿", // 전자서명 템플릿 이름
    "slug": "template-slug" // slug(문자)
  }
}
```

> **참고**: `SIGNATURE_TEMPLATE_DELETED` 이벤트는 계약서 태그 필터와 상관없이 발송됩니다.

<br>

## (5) 영업문서 카테고리 웹훅 이벤트 본문

영업문서 카테고리의 웹훅 요청의 Body 예시입니다.

```json
{
  "eventType": "DOCUMENT_CREATED",
  "createdAt": "2024-11-15T00:00:00.000Z",
  "document": {
    "id": 1,
    "uuid": "ed976505-bcbd-47bd-913d-f4cde05dea7a", // 문서 식별값 (uuid 값을 api에서 사용)
    "title": "A컴퍼니 영업문서", // 영업문서 이름
    "status": "CREATED", // 영업문서 상태 (CREATED, SENT, APPROVED, DELETED)
    "createdAt": "2024-11-01T00:00:00.000Z",
    "updatedAt": "2024-11-01T00:00:00.000Z"
  }
}
```

<br>

## (6) 웹훅 서명 검증

웹훅 요청이 프릭스에서 보낸 것인지 수신 서버에서 확인할 수 있습니다.

### 시크릿 키 사용 켜기

* "설정 메뉴 > 웹훅 관리"에서 웹훅을 등록하거나 편집할 때 `시크릿 키 사용`을 켭니다.
* 시크릿 키는 발급 직후 뜨는 창에 표시되며, 이후에는 웹훅 편집 창에서 다시 확인하고 복사할 수 있습니다. (`whsec_`로 시작하는 문자열)
* `시크릿 키 사용`을 켠 웹훅에만 아래 헤더가 추가됩니다. 켜지 않은 웹훅의 요청은 기존과 같습니다.
* 껐다가 다시 켜면 새 시크릿 키가 발급되며, 이전 시크릿 키는 사용할 수 없습니다.

### 요청 헤더

| 헤더                 | 설명                                                                     | 예시                   |
| ------------------ | ---------------------------------------------------------------------- | -------------------- |
| `X-Prix-Timestamp` | 요청을 보낸 시각입니다. (초 단위 유닉스 시간)                                            | `1762740000`         |
| `X-Prix-Signature` | `{timestamp}.{body}`를 시크릿 키로 HMAC-SHA256 한 값(hex)에 `sha256=`를 붙인 값입니다. | `sha256=5d41402a...` |

### 검증 순서

1. `X-Prix-Timestamp`와 `X-Prix-Signature` 헤더를 읽습니다.
2. 타임스탬프가 현재 시각과 5분 이상 차이 나면 요청을 거부합니다. (재전송 공격 방지를 위해 권장)
3. `{타임스탬프}.{요청 Body 원문}`을 시크릿 키로 HMAC-SHA256 한 값을 계산합니다.
4. 계산한 값과 `X-Prix-Signature`의 `sha256=` 뒤 값을 비교합니다.

> **참고**: 서명은 요청 Body **원문**으로 계산합니다. Body를 JSON으로 파싱한 뒤 다시 문자열로 만들면 값이 달라질 수 있으므로, 전달받은 원문 그대로 사용해 주세요.

### Node.js 예제

```javascript
const crypto = require("crypto");
const express = require("express");

const WEBHOOK_SECRET = process.env.PRIX_WEBHOOK_SECRET; // whsec_...
const TOLERANCE_SECONDS = 5 * 60;

const app = express();

// 서명 검증에 Body 원문이 필요하므로 raw로 받습니다.
app.post("/prix/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const timestamp = req.get("X-Prix-Timestamp");
  const signature = req.get("X-Prix-Signature");
  if (!timestamp || !signature) {
    return res.status(401).send("missing signature");
  }

  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - Number(timestamp)) > TOLERANCE_SECONDS) {
    return res.status(401).send("expired timestamp");
  }

  const rawBody = req.body.toString("utf8");
  const expected =
    "sha256=" +
    crypto
      .createHmac("sha256", WEBHOOK_SECRET)
      .update(`${timestamp}.${rawBody}`)
      .digest("hex");

  const isValid =
    signature.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
  if (!isValid) {
    return res.status(401).send("invalid signature");
  }

  const event = JSON.parse(rawBody);
  // event.eventType에 따라 처리합니다.
  res.sendStatus(200);
});
```

> **참고**: 웹훅 로그에서 재호출한 요청은 재호출 시각 기준으로 새로 서명됩니다.
