콘텐츠로 이동

Notion API 웹훅과 변경 감지

개요

사용자가 노션에서 콘텐츠를 고치면, 우리 시스템이 그 변화를 알아야 웹사이트에 반영할 수 있어요. 매번 Notion 전체를 다시 조회(polling)하는 건 비효율적이죠. Notion의 웹훅(webhook) 은 "페이지·데이터베이스가 바뀌면 Notion이 우리 서버로 보안 HTTP POST 요청을 보내주는" 기능이에요. 공식 문서는 이를 "폴링 대신, 중요한 일이 생긴 순간 Notion이 알려주는 것"으로 설명해요. 이 페이지는 구독 생성, 검증(verification), 이벤트 처리를 풀어요.

핵심 개념

웹훅이 어떻게 동작하나

연결(connection)이 page.content_updated 같은 이벤트에 구독돼 있다고 해볼게요. 사용자가 Notion에서 페이지 제목을 고치면, 잠시(공식 문서 예시에선 약 1분 이내) 후 Notion이 설정된 엔드포인트로 웹훅 요청을 보내요. 이벤트 페이로드에는 페이지 ID, 이벤트 타입, 타임스탬프 같은 메타데이터가 담겨요. 우리 서버는 그 이벤트를 받아 검증하고, 페이지 ID로 Notion API를 다시 호출해 변경된 내용을 가져와 반영해요. 이렇게 폴링 없이 "바뀐 순간"에만 반응할 수 있어요.

구독 만들기 (Step 1)

웹훅을 받으려면 연결 설정에서 구독(subscription)을 만들어야 해요. 할 일은 이렇게 정리돼요.

  1. 연결 설정의 Webhooks 탭에서 "+ Create a subscription".
  2. 공개 Webhook URL을 입력 — 반드시 SSL이고 공개 접근 가능한 엔드포인트여야 해요. localhost는 도달 불가예요.
  3. 어떤 이벤트 타입에 구독할지 선택 (나중에 수정 가능).
  4. Create subscription 클릭.

이 시점엔 아직 검증 전이라, 엔드포인트가 검증 요청에 응답할 수 있는지 확인해야 해요.

구독 검증하기 (Step 2)

구독을 만들면 Notion이 웹훅 URL로 1회성 POST 요청을 보내요. 그 본문에 verification_token 이 들어 있어요. 우리 엔드포인트는 그 요청에서 verification_token을 추출하고, 검증을 완료(응답)해야 구독이 활성화돼요. 이 토큰은 나중에 페이로드 유효성 검증 설정에도 쓸 수 있어 안전하게 보관하면 돼요.

{
  "verification_token": "secret_tMrlL1qK5vuQAh1b6cZGhFChZTSYJlce98V0pYn7yBl"
}

이벤트 처리와 멱등성

실제 이벤트가 오면, 우리는 그 이벤트가 "어느 페이지가 바뀌었다"는 신호라는 것만 알고 있어요. 실제 새 콘텐츠는 그 페이지 ID로 API를 호출해 가져와요. 여기서 유의할 점은 웹훅이 중복으로 올 수 있다는 거예요. 같은 변경에 대해 이벤트가 두 번 오면 후속 처리가 두 번 일어나면 안 되므로, 이벤트를 한 번만 처리하는 멱등성을 설계해야 해요.

실제 적용 (데이터스케쳐스)

웹빌더의 대표 흐름 Notion → 웹사이트에서 웹훅은 "사용자가 노션을 고쳤을 때 우리가 알아차리는" 수단이에요. 사용자가 페이지를 수정하면 page.content_updated 웹훅이 우리 서버로 오고, 우리는 그 페이지 ID로 새 내용을 가져와 마크다운 변환 후 웹 페이지를 갱신해요. 폴링을 돌릴 필요 없이 변경만 전파되죠.

운영할 때 주의할 점은 웹훅 엔드포인트가 SSL 공개 URL이어야 하고, 중복 이벤트를 멱등으로 처리해야 한다는 거예요. 또 검증 토큰을 알맞게 처리하지 않으면 구독이 활성화되지 않으니, 검증 절차를 먼저 확인해요. 인증받는 방법은 인증, 본문을 읽는 방법은 데이터베이스 질의에서 이어져요.

더 알아보기