25.09.17 / JUN
노션 API는 새롭게 각광받는 소프트웨어 비즈니스를 시작할 수 있는 멋진 방법입니다.
- P1. 노션 마켓플레이스 시작하기
- P2. 노션 API 키 생성하기
- P3. 노션 웹훅 연결
P1. 노션 마켓플레이스 시작하기
노션 생태계에서 비즈니스를 하려면 가장 먼저 노션 마켓플레이스에서 프로필 작성부터 시작하세요.
노션 마켓플레이스에서 팔 수 있는 3대 아이템
- 템플릿
- 서비스
- API통합
노션 서비스란?
노션 응용 소프트웨어 활용 및 개발 파트너로서 컨설팅, 강의 서비스를 제공하는 것을 의미해요.
노션 파트너 신청을 하려는 분들은 먼저 아래 인증 과정을 수료하고 테스트에 통과해주세요.
API 인테그레이션에서 노션 API 키를 생성할 수 있어요.
키 유형은 프라이빗(인터널), 퍼블릭 등 두 가지가 있는데, 바이브코더를 위해서는 일단 프라이빗 키 생성을 권장해요.
노션 API 키 생성 완료!
노션 API 키 권한도 설정
노션 라이브 이벤트 수신위한 웹훅 엔드포인트 추가하려면,
- 웹훅 기능을 할 JS 파일, 노션 toml 파일을 깃허브 리포에 추가하고
2. 넷리파이같은 서버리스 환경에 해당 깃허브 리포를 가리키는 앱 배포하고, 웹훅 URL 엔드포인트 얻어서
3. 노션 라이브 이벤트 수신 위한 웹훅 URL 추가
P2. 노션 API 키 생성하기
1) 통합(Integration) 만들기와 키 발급
- Notion에서 새 Integration을 생성하고 Internal Integration Token을 발급받습니다.
- 워크스페이스에서 API로 접근할 데이터베이스/페이지를 해당 Integration과 공유해야 합니다. 공유하지 않으면 403 권한 오류가 납니다.
- 키는 서버 측 환경변수로 보관하세요. 클라이언트에 직접 노출하지 마세요. 프록시 서버를 두는 방식을 권장합니다.
2) 권한 연결: 데이터베이스/페이지를 Integration에 공유
- 데이터베이스 우측 상단 ••• → 연결 → 방금 만든 Integration 선택
- 페이지 기반 읽기만 필요해도 상위 페이지 또는 데이터베이스 단위로 공유하는 편이 관리가 쉽습니다.
3) 빠른 호출 예시
- 공통: Authorization 헤더에 Bearer {NOTION_TOKEN} 추가, Notion-Version 지정
curl 예시
curl -X POST https://api.notion.com/v1/databases/{DATABASE_ID}/query \ -H “Authorization: Bearer $NOTION_TOKEN” \ -H “Notion-Version: 2022-06-28” \ -H “Content-Type: application/json” \ -d ‘{“page_size”:10}’
JavaScript (Node)
import { Client } from “@notionhq/client”; const notion = new Client({ auth: process.env.NOTION_TOKEN }); const res = await notion.databases.query({ database_id: process.env.NOTION_DB_ID, page_size: 10, }); console.log(res.results.map(p => p.id));
Python
from notion_client import Client notion = Client(auth=os.environ[“NOTION_TOKEN”]) res = notion.databases.query(database_id=os.environ[“NOTION_DB_ID”], page_size=10) print([p[“id”] for p in res[“results”]])
4) 자주 하는 작업 패턴
- 데이터베이스 조회: 필터, 정렬로 필요한 행만 가져오기
- 페이지 생성: 특정 데이터베이스에 속성 값과 함께 행 추가
- 페이지 업데이트: 텍스트, 선택, 멀티선택, 날짜 등 속성 수정
- 블록 읽기/쓰기: 페이지 본문을 블록 단위로 읽고 추가하기
- 검색 API: 제목 키워드로 페이지/DB 찾기
- 권장 구조: “읽기 전용 서버 프록시” → 프론트엔드는 /api/notion 같은 내부 엔드포인트 호출로 키 보호
노션 페이지 생성 예시 (Node)
await notion.pages.create({ parent: { database_id: process.env.NOTION_DB_ID }, properties: { “Name”: { title: [{ text: { content: “New item” } }] }, “Status”: { select: { name: “In Progress” } }, }, });
5) 스키마 다루기 팁
- 데이터베이스의 속성 이름과 타입은 API 요청 시 정확히 일치해야 합니다.
- select, status 옵션 값은 대소문자까지 동일해야 합니다.
- 변경이 잦다면 “스키마를 코드화”해 동기화 스크립트를 두면 유지보수가 편합니다.
6) 배포와 보안
- 환경변수: NOTION_TOKEN, NOTION_DB_ID를 .env 또는 비밀 관리 서비스에 저장
- 클라이언트 키 노출 금지: 브라우저에서 직접 Notion API 호출하지 말고, 서버리스 함수나 Edge 프록시를 사용
- 최소 권한: Integration을 필요한 DB/페이지에만 공유하세요
7) 장애와 한도 대응
- 레이트리밋에 대비해 지수적 백오프 재시도
- 대용량 목록은 cursor 기반 pagination 사용
- 일관성: 쓰기 직후 읽기 시 약간의 지연을 고려해 재시도 로직을 넣으면 안전
8) 학습·실습 로드맵
- Day 1: Integration 생성 → 토큰 보관 → 데이터베이스 query로 목록 그리기
- Day 2: 페이지 생성/업데이트 → 프론트에서 카드 뷰로 표시
- Day 3: 서버 프록시 도입 → 배포 자동화(CI) → 간단 테스트 추가
P3. 노션 웹훅 연결
- 구독 인증을 위해 웹훅 URL 생성
2. 토큰 전송하면 앱이 배포된 서버 영역의 Function log에 시크릿 키 생성
3. 이 시크릿 키를 복사해서 인증 토큰 영역에 붙여넣고 구독 인증 누르면… 웹훅 인증 및 활성화 성공!
“인증 토큰”은 내가 만드는 웹훅 서버로 Notion이 보낸 첫 번째 “구독 인증 요청” 속에 들어 있습니다. 즉, 발급받는 곳이 따로 있는 게 아니라, 내 웹훅 엔드포인트 로그에서 확인해 붙여 넣는 값입니다.
간단 절차
1) 웹훅 URL을 입력하고 “토큰 재전송”을 누른다.
2) 내 서버의 요청 로그를 본다. Netlify Functions라면:
Netlify 대시보드 → Site → Functions → 해당 함수 → Logs에서 최근 호출 확인
또는 로컬에서 netlify dev 실행 중이면 터미널 로그 확인
3) 들어온 최초 요청의 JSON 바디에 verification token이 포함된다. 그 값을 복사해 “인증 토큰” 입력칸에 붙여 넣고 “구독 인증”을 누른다.
