> 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).
# 웹훅 이용하기
프릭스에서 제공하는 웹훅 이벤트 목록입니다.
워크스페이스 내 "설정 메뉴 > 웹훅 관리"에서 웹훅을 관리할 수 있습니다.
* 직접 원하는 이벤트에 맞게 웹훅을 추가할 수 있습니다.
* 원하는 계약 태그를 선택하여 해당 태그가 붙은 계약서 이벤트에만 웹훅을 발송할 수 있습니다. (태그 필터 미등록 시 모든 이벤트 발송)
* 웹훅 로그 목록을 확인할 수 있습니다.
## 웹훅 태그 필터
**계약서 이벤트**( 계약서 생성, 전자서명 요청/체결/참여/만료 이벤트)에 대해 특정 계약 태그를 선택하여 웹훅을 등록할 수 있습니다.
### 태그 필터의 동작 방식
* **태그 미등록**: 웹훅이 모든 계약서 이벤트를 수신합니다.
* **태그 등록**: 해당 태그가 붙은 계약서 이벤트에만 웹훅이 발송됩니다.
* **다중 태그 등록**: 등록된 태그 중 **하나 이상**이 계약서에 붙어있으면 웹훅이 발송됩니다
### 태그 필터 제약사항
* **영업문서 이벤트**(`DOCUMENT_*`)와 태그 필터는 함께 사용할 수 없습니다.
* 영업문서에는 태그가 없기 때문에, 웹훅 UI에서 영업문서 이벤트를 선택하면 태그 입력 필드가 자동으로 숨겨집니다.
* 계약서 이벤트와 영업문서 이벤트를 함께 선택한 경우, 혼합된 상태에서도 태그 필터링이 불가능합니다.
* **전자서명 템플릿 삭제 이벤트**(`SIGNATURE_TEMPLATE_DELETED`)는 계약서 태그 필터 대상이 아닙니다.
* 해당 이벤트를 구독한 웹훅에는 태그 설정과 상관없이 이벤트가 발송됩니다.
## (1) 웹훅 이벤트 타입
웹훅으로 등록할 수 있는 이벤트 타입은 아래와 같습니다.
| 이벤트 타입 | 설명 | 카테고리 |
| ---------------------------- | ---------------------------------------------------------- | -------- |
| CONTRACT\_CREATED | 계약서 등록 이벤트입니다. | 계약서 |
| SIGNATURE\_CREATED | 전자서명 생성 이벤트입니다. | 전자서명 |
| SIGNATURE\_CONCLUDED | 모든 참여자가 서명을 완료하여 계약이 체결되는 이벤트입니다. | 전자서명 |
| SIGNATURE\_PARTICIPATED | 개별 전자서명 참여자의 서명 완료 이벤트입니다. | 전자서명 |
| SIGNATURE\_EXPIRED | 전자서명이 체결되지 않고 만료된 경우, 만료일 다음날 오전 11시에 호출되는 전자서명 만료 이벤트입니다. | 전자서명 |
| SIGNATURE\_TEMPLATE\_DELETED | 전자서명 템플릿이 삭제되는 이벤트입니다. | 전자서명 템플릿 |
| DOCUMENT\_CREATED | 영업문서 생성 완료 이벤트입니다. | 영업문서 |
## (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에 포함됩니다.
## (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"
}
}
```
## (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` 이벤트는 계약서 태그 필터와 상관없이 발송됩니다.
## (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"
}
}
```