노션이 제공하는 강력한 데이터베이스 기능을 활용하다 보면, 단순히 노션 내부에서만 데이터를 관리하는 것에 그치지 않고 외부 서비스와의 연동을 꿈꾸게 됩니다. 예를 들어, 슬랙(Slack)에서 받은 피드백을 자동으로 노션 DB에 쌓거나, 노션에서 업무 상태가 변경되면 팀원들에게 실시간으로 알림을 보내고 싶을 때가 있습니다. 하지만 막상 노션 페이지에 새로운 데이터베이스를 만들고 외부 서비스와 연동하려고 시도하면, 'API 키를 어디에 입력해야 하는지', '왜 계속 권한 거부 오류가 뜨는지' 막막한 상황에 직면하게 됩니다. 이 문제가 발생하는 근본적인 이유는 노션이 다른 SaaS 도구와는 다른 독특한 보안 및 권한 구조를 채택하고 있기 때문입니다. 노션은 단순히 개인 설정에서 API 키를 발급받는 것으로 끝나지 않고, 별도의 '내 통합(My Integrations)'이라는 메뉴에서 인증 정보를 발급받아야 하며, 발급된 토큰(Token)을 연동하려는 특정 데이터베이스 페이지에서 개별적으로 승인해주는 2단계 인증 과정을 거쳐야만 비로소 통신이 가능합니다. 이 글에서는 실제 현장에서 적용한 세 가지 구체적인 사례를 통해 노션 API를 활용해 Slack과 연동하는 전체 과정을 단계별로 상세히 다룹니다. 또한, 단순한 연동을 넘어 데이터베이스 ID를 정확히 추출하는 방법과 토큰 관리법, 그리고 발생 가능한 오류에 대한 대응책까지 포함한 실질적인 노션 API 통합 가이드를 제공합니다.
- 노션 개발자 포털에서 통합을 생성하고 '내부 통합 토큰'을 발급받는 방법
- 데이터베이스 URL을 분석하여 32자리 고유 ID를 추출하고 권한을 연결하는 절차
- Slack 워크플로우 빌더와 Make를 활용해 양방향 데이터를 주고받는 설정 방법
노션 API와 Slack을 연동해 업무를 자동화하면 데이터 업데이트를 실시간으로 전달하고, 팀 커뮤니케이션을 간소화해 평균 30%의 작업 시간을 절감할 수 있습니다.
사례 1: 데이터베이스 ID 추출 및 API 연결 테스트
첫 번째 사례는 스타트업 기획팀에서 주간 회의록을 관리하는 데이터베이스를 구축하고, 이를 외부 서비스와 연동하기 위해 사전 준비를 진행한 과정입니다. API 연동 작업에서 가장 많은 사용자가 실패하는 단계는 API 키를 발급받았음에도 불구하고 데이터베이스가 응답하지 않는 상황입니다. 개발자들은 흔히 "토큰이 있으면 되는 것 아닌가?"라고 생각하지만, 노션 API는 복잡한 권한 체계를 가지고 있어 단순히 토큰만 있다고 모든 데이터에 접근할 수 없습니다. 이는 데이터베이스 ID를 잘못 가져왔거나, 특정 페이지에 토큰 사용 권한을 명시적으로 부여하지 않아서 발생하는 대표적인 오류입니다.
이 사례에서는 API 연동을 위해 필수적인 두 가지 요소인 '내부 통합 토큰(Integration Token)'과 '데이터베이스 ID(Database ID)'를 확보하는 과정을 집중적으로 다룹니다. 노션 개발자 문서에 따르면 API 버전 2022-06-28을 기준으로 모든 요청 헤더에는 인증 토큰과 노션 버전 정보가 반드시 포함되어야 합니다. 이 과정을 생략하거나 헤더를 잘못 구성하면 HTTP 401 Unauthorized 오류가 반환되므로 각별한 주의가 필요합니다. 실무에서는 이 과정을 자동화 스크립트 작성 전에 반드시 수동으로 검증하는 것이 좋습니다.
내 통합 생성 및 토큰 발급
가장 먼저 노션의 https://www.notion.so/my-integrations 페이지에 접속해야 합니다. 이 페이지는 일반 노션 설정 메뉴와는 분리되어 있습니다. 상단의 '새로운 통합' 버튼을 클릭한 후, 기본 정보(이름, 연결된 워크스페이스, 유형)를 입력합니다. 이때 '유형'은 '내부'로 선택해야 개인 용도나 내부 팀 자동화에 무료로 사용할 수 있습니다. 생성이 완료되면 '내부 통합 토큰'이라는 항목이 나타나는데, 이 토큰은 secret_로 시작하는 긴 문자열입니다. 이 토큰은 보안상 생성 시점에 한 번만 완전하게 공개되므로, 반드시 안전한 곳에 복사해 두어야 합니다.
기능 권한(_capacities) 설정 확인
토큰을 발급받을 때 해당 통합이 수행할 수 있는 작업의 범위를 미리 파악해야 합니다. 기본적으로 읽기(Read), 쓰기(Update), 삽입(Insert) 권한이 포함되어 있지만, 특정 기능을 제한해야 한다면 이 단계에서 설정을 확인해야 합니다. 대부분의 자동화 작업은 '콘텐츠 읽기 및 쓰기' 권한이 필요하므로, 관련 설정이 비활성화되어 있지 않은지 체크하세요.
데이터베이스 ID 추출
연동하려는 데이터베이스가 포함된 노션 페이지의 URL을 분석해야 합니다. 브라우저 주소창에 표시되는 URL 구조는 보통 https://www.notion.so/username/Page-ID?v=... 형태입니다. 여기서 주의할 점은 페이지 이름이나 사용자 이름이 아닌, URL 경로에 포함된 32자리 영문 숫자 조합된 부분이 바로 ID라는 점입니다. 만약 데이터베이스가 페이지 전체(Full Page)로 뷰되고 있다면 해당 URL의 ID가 데이터베이스 ID이지만, 만약 데이터베이스가 페이지 내부(In-page)에 존재한다면, 해당 데이터베이스를 클릭하여 뷰를 확장한 뒤 주소창의 URL이 변경되는 것을 확인하고 그때의 32자리 ID를 가져와야 합니다.
페이지에 연결 권한 부여 (가장 중요)
많은 사용자가 이 단계를 놓쳐서 403 Forbidden 오류를 경험합니다. 데이터베이스 페이지 우측 상단의 '더보기(...)' 메뉴를 클릭하고 하단의 '연결(Connect)' 메뉴를 선택합니다. 팝업되는 목록에서 방금 생성한 통합 이름을 검색하여 추가합니다. 이 단계는 "이 데이터베이스의 제어권을 방금 만든 봇에게 위임한다"는 의미와 같습니다. 이 단계를 수행하지 않으면 API가 아무리 정상적인 토큰을 가지고 요청을 보내도, 노션 서버는 "이 봇은 이 집에 들어올 자격이 없다"며 응답을 거절합니다.
API 요청 헤더 구성
이제 실제 통신을 위한 준비 단계입니다. API 요청을 보낼 때는 두 가지 필수 헤더가 필요합니다. 하나는 Authorization: Bearer {TOKEN}이고, 다른 하나는 Notion-Version: 2022-06-28입니다. 버전 정보는 노션 API의 업데이트에 따라 달라질 수 있으므로, 최신 문서를 확인하는 것이 습관화되어야 합니다.
연결 테스트 수행
모든 설정이 마무리되면 실제로 데이터를 가져올 수 있는지 테스트해야 합니다. 가장 확실한 방법은 데이터베이스의 메타 정보를 조회하는 GET 요청을 보내는 것입니다. 성공한다면 JSON 형식으로 데이터베이스의 속성(Properties) 정보와 타이틀 정보가 반환됩니다.
macOS 터미널이나 Windows PowerShell을 사용하여 연결 테스트를 진행할 때는 반드시 따옴표를 제대로 처리해야 합니다. 특히 Bearer 토큰에 포함된 특수문자가 쉘 명령어와 충돌하지 않도록 전체 문자열을 감싸는 데 주의하세요. 아래 명령어에서
YOUR_DATABASE_ID와 YOUR_INTEGRATION_TOKEN을 실제 값으로 교체한 뒤 실행해
동영상으로 보는 노션 API 통합 가이드
글로 충분하지 않다면 관련 영상을 함께 보세요. 클릭하면 YouTube에서 검색 결과로 이동합니다.
▶ YouTube에서 “노션 API 통합 가이드” 영상 보기
자주 묻는 질문
Q. 노션 API와 Slack을 연동하려면 어떤 권한이 필요하나요?
A. 노션 API 키는 해당 워크스페이스에 대한 읽기·쓰기 권한이 있는 통합에 부여해야 합니다. Slack에서는 봇 토큰에 채널에 메시지를 보내고 읽을 수 있는 권한(scopes)을 추가해야 원활히 동작합니다.
Q. 연동 시 데이터 동기화는 실시간으로 이뤄지나요?
A. 기본적으로는 웹훅이나 주기적인 폴링을 설정해 일정 간격(예: 5분)으로 동기화됩니다. 실시간 알림이 필요하면 Slack의 이벤트 서브스크립션을 활용해 즉시 전송하도록 구성할 수 있습니다.
Q. 노션 페이지에 변경이 생겼을 때 Slack으로 알림을 보내는 방법은?
A. 노션의 'database'에 변경이 있을 때 트리거되는 자동화 툴(예: Zapier, Make)이나 직접 만든 서버리스 함수에서 API를 호출해 Slack Webhook URL에 메시지를 전송하면 됩니다. 메시지 포맷은 Slack Block Kit을 사용해 가독성을 높일 수 있습니다.
Q. 연동을 해제하거나 토큰을 교체하려면 어떻게 해야 하나요?
A. 노션 관리 페이지에서 기존 통합을 삭제하거나 새로운 API 토큰을 발급받아 설정 파일을 교체하면 됩니다. Slack에서도 앱 설정 페이지에서 봇 토큰을 재생성하거나 앱 자체를 삭제 후 재설치하면 연동을 초기화할 수 있습니다.
함께 읽으면 좋은 글