> ## Documentation Index
> Fetch the complete documentation index at: https://developers.bottari.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 웹훅 구독하기

> 연동에 웹훅 구독을 만들고 받을 주소를 인증합니다.

웹훅을 구독하면 연동이 읽을 수 있는 대상이 바뀔 때 Bottari가 지정한 주소로 POST를 보냅니다. 본문에는 내용 없이 ID와 종류만 있습니다. 받는 서버는 그 ID로 API를 호출해 최신 값을 읽습니다.

구독은 연동마다 하나입니다. 받을 주소가 2개 필요하면 연동을 2개 만드세요. 구독은 팀 소유자만 관리할 수 있습니다.

## 구독 만들기

**1. 받을 서버 준비하기**

주소로 온 POST에 2xx로 응답하고 본문의 `verification_token`을 확인할 수 있게 하세요.

> [!NOTE]
>
> [서명 검증 예제 자세히 알아보기 →](https://developers.bottari.ai/ko/webhooks/signature.md)

**2. 구독 만들기**

연동 상세의 `연결된 데이터베이스` 아래 `웹훅`에서 `구독 만들기`를 누르고, `웹훅 구독 만들기` 창에서 주소를 입력한 뒤 이벤트를 고르고 `만들기`를 누르세요.

> [!NOTE]
>
> 이벤트는 처음에 모두 선택되어 있습니다. API 버전은 `2026-03-11`로 고정됩니다. `comment.*` 이벤트를 받으려면 `권한`에서 `댓글 읽기`도 켜세요.

**3. 인증 토큰 받기**

Bottari가 그 주소로 POST를 보내면 본문에서 인증 토큰을 확인하세요.

```http theme={null}
POST /your/webhook HTTP/1.1
Content-Type: application/json
User-Agent: bottari-integration/1.0
x-bottari-signature: sha256=...

{"verification_token":"bts_..."}
```

> [!NOTE]
>
> `구독 인증` 창이 자동으로 열립니다. 서버가 2xx가 아닌 코드로 응답해도 토큰을 받았다면 인증할 수 있습니다.

**4. 토큰 넣기**

`구독 인증` 창에 받은 토큰을 넣고 `인증`을 누르세요.

> [!NOTE]
>
> 창을 닫았다면 주소 옆의 `인증`을 누르세요. 상태가 `켜짐 · API 버전 2026-03-11`로 바뀌면 그 뒤의 변경부터 이벤트를 전송합니다. 인증 전의 변경은 전송하지 않습니다.

**5. 토큰 보관하기**

인증 토큰을 서버의 환경 변수에 넣으세요.

> [!WARNING]
>
> 인증 토큰은 서명을 검증하는 키입니다. 화면과 API에 다시 표시되지 않습니다.

## 인증 전에 할 수 있는 작업

* `토큰 다시 보내기`: 같은 토큰을 다시 보냅니다. 구독마다 시간당 10번까지입니다.
* 주소 바꾸기: `구독 인증` 창에서 주소를 고치고 `이 주소로 토큰 보내기`를 누르세요. 새 토큰을 새 주소로 보내고, 이전 토큰은 사용할 수 없습니다.

틀린 토큰을 넣으면 `토큰이 맞지 않아요.`가 표시됩니다.

## 인증 뒤에 할 수 있는 작업

* `고치기`: 받을 이벤트를 언제든 고칠 수 있습니다.
* 주소 바꾸기: 잠겨 있어 바꿀 수 없습니다. 구독을 지우고 새로 만드세요.
* `일시 중지` · `다시 시작`: 멈춘 동안의 변경은 다시 시작해도 전송하지 않습니다. 전송을 기다리던 이벤트도 지웁니다.
* `구독 지우기`: 같은 주소도 처음부터 다시 인증해야 합니다.

인증한 토큰을 잃어버렸다면 구독을 지우고 새로 만드세요. 연동을 지우면 구독도 함께 지워집니다.

연동 상세의 `전송 실패`에서 실패 횟수와 마지막 시각을 확인할 수 있습니다. [재시도와 자동 일시 중지 자세히 알아보기 →](https://developers.bottari.ai/ko/webhooks/retries.md)

## 받을 주소 규칙

* `https`만 받습니다.
* 2,048자까지 사용할 수 있습니다.
* 공개 주소여야 합니다. 사설 주소로 해석되는 호스트는 거절합니다.
* 주소에 아이디와 비밀번호를 넣을 수 없습니다. 예: `https://user:pass@example.com`
* 찾을 수 없는 호스트는 거절합니다.
* 리다이렉트는 따라가지 않습니다. 3xx 응답은 실패로 처리합니다.

## 이벤트를 받은 뒤 다시 읽기

이벤트의 ID는 API가 반환하는 값과 같아 바로 다시 읽을 수 있습니다.

| 이벤트 값 | 다시 읽는 엔드포인트 |
| - | - |
| `entity.id`(`page`) | `GET /v1/pages/{id}` |
| `updated_properties`의 속성 ID | `GET /v1/pages/{id}/properties/{property_id}` |
| `updated_blocks`의 블록 ID | `GET /v1/blocks/{id}` |
| `entity.id`(`data_source`) | `GET /v1/data_sources/{id}` |
| `entity.id`(`database`) | `GET /v1/databases/{id}` |
| `entity.id`(`comment`) | `GET /v1/comments/{id}` |

휴지통에 있는 행은 200과 `in_trash: true`를 반환합니다. `updated_blocks`의 지운 블록 ID는 404를 반환합니다.


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