Skip to content

Notion API

웹빌더가 '노션이 바로 웹사이트가 된다'는 약속을 하려면, 사용자가 노션에 적은 콘텐츠를 우리 시스템이 읽을 수 있어야 해요. 그런데 노션은 우리가 만든 제품이 아니니까, 노션 페이지와 DB에 접근하려면 노션이 허락한 문을 통과해야 하죠. Notion API는 Notion 페이지·DB를 읽고 쓸 수 있는 공식 API예요. 웹빌더가 콘텐츠를 Notion에서 가져오는 핵심 경로로, 🟢 운영 상태에서 실제로 돌고 있어요.

한눈에 보면 이렇게 단계가 이어져요. 인증(OAuth) → 읽기(페이지·DB·블록) → 변경 감지(Webhook) → 변환(마크다운·웹 문서) 순서예요. 이 네 단계가 Notion에서 웹사이트로 가는 핵심 경로를 이룹니다.

핵심 개념

  • API 종류와 인증 — 페이지·블록 조회는 API 키 방식으로도 가능하지만, 고객별 콘텐츠에 접근할 땐 OAuth로 사용자 동의를 받는 쪽을 씁니다. 누구의 콘텐츠를 읽는지가 인증 방식의 기준이 돼요.
  • 공식 API (developers.notion.com) — 노션이 공식으로 제공하는 프로그래밍 인터페이스예요. 페이지·DB를 조회하고, 블록을 읽고, 새로운 콘텐츠를 작성할 수 있습니다.
  • OAuth 인증 — 사용자 계정을 대신해 API를 쓰려면 노션의 OAuth 흐름으로 인증받아야 해요. 사용자가 '이 앱에 노션 접근을 허용'하면 우리가 액세스 토큰을 받아 대신 요청하죠.
  • Webhook — '콘텐츠에 변경이 생겼다'는 이벤트를 노션이 우리 서버로 알려주는 콜백이에요. 사용자가 노션을 고쳤을 때 매번 폴링하지 않아도, 변경 신호를 받아서 재동기화할 수 있어요.
  • 블록 기반 구조 — 노션 콘텐츠는 블록(문단·제목·표·이미지 등) 단위로 구성돼요. API로 블록을 가져와서, 그 구조를 웹 문서 요소(마크다운·HTML)로 바꾸는 게 변환의 핵심이에요.
  • 콘텐츠 소스로서의 역할 — Notion은 콘텐츠를 쓰는 원천(Source of truth)이고, 우리는 그걸 읽어 웹사이트로 만드는 쪽이에요. '쓰는 곳'(Notion)과 '보여지는 곳'(웹)을 잇는 다리 역할을 합니다.

사용 사례 / 실제 적용

대표 흐름이 Notion → 웹빌더 → 커스텀 도메인 → 결제의 첫 단계예요. 사용자가 Notion에 콘텐츠를 쓰면, 웹훅+API로 우리가 그 변경을 감지하고 블록을 가져와요. 그걸 마크다운으로 변환해 웹사이트 페이지로 만들죠. 다음 단계(도메인·결제)는 외부 연동 허브와 Cloudflare·Toss Payments 페이지에서 이어져요.

이 연동을 만들 때 놓치기 쉬운 점은 인증과 변경 감지의 수명 주기예요. OAuth 토큰은 만료될 수 있고, 웹훅은 중복으로 올 수 있어요. 그래서 '토큰이 만료됐을 때 다시 인증받는 흐름'과 '중복 이벤트를 한 번만 처리하는 멱등성'을 미리 설계해 두는 게 중요해요. 이는 Notion뿐 아니라 모든 외부 연동의 공통 규칙이에요. 운영할 때는 이 점도 살펴보면 좋아요.

  • 변경만 전파 — 콘텐츠 전체를 매번 다시 가져오기보다, 바뀐 블록만 재동기화하면 변환 비용을 줄여요.
  • 포맷 변환 유지 — 노션 블록 → 마크다운 변환은 구조가 세세할수록 빠뜨리기 쉬워요. 변환 검증 케이스를 함께 관리하죠.
  • 동기화 실패 처리 — 동기화가 실패했을 때 자동 재시도와, 그래도 안 되면 알림으로 남기는 흐름을 정해둬요.
  • 인증 만료 대응 — OAuth 토큰이 만료되면 사용자 재동의를 요청하는 흐름을 미리 만들어 둬요.
  • 가져온 데이터 검증 — Notion에서 읽은 블록이 뒤의 변환·렌더링에서 깨지지 않도록 중간 검증을 둬요.
  • 권한 범위 최소화 — 필요한 페이지·DB만 접근하도록 OAuth 권한을 최소로 잡아 보안 노출을 줄여요.
  • 동기화 상태 기록 — 마지막으로 언제·어디까지 동기화했는지를 남겨야, 끊겼을 때 이어서 처리할 수 있어요.
  • 벤더 변경 대비 — 외부 API 특성은 남의 손에 있으니, 연동 코드를 바꿔 끼울 수 있게 인터페이스로 분리해 두는 게 좋아요.

심화 챕터

Notion 연동의 세 단계는 아래 챕터에서 공식 문서를 기준으로 다뤄요.

더 알아보기