Skip to main content

Webhook 엔드포인트가 뭔가요?

Webhook 엔드포인트는 Tiro가 이벤트 발생 시 HTTP POST 요청을 보내는 URL이에요. Tiro Platform에 등록하면 API를 폴링하지 않고 이벤트를 받을 수 있어요.

Webhook 동작 방식

  1. 설정: 애플리케이션에 webhook endpoint를 마련해요
  2. 등록: 받고 싶은 이벤트를 위해 endpoint를 추가해요
  3. 수신: 이벤트가 발생하면 즉시 알림을 받아요
  4. 처리: 애플리케이션에서 이벤트 데이터를 처리해요

이벤트 & 리소스 구조

Webhook은 이벤트(Event)리소스(Resource) 를 중심으로 구성돼요.

이벤트(Events)

이벤트는 워크스페이스에서 발생하는 동작을 나타내요. 자세한 내용은 Note Events, Note Document Events, Note Summary Events, FolderNote Events, 음성 파일 API 개요를 참고하세요. Webhook 이벤트는 메타데이터만 포함하며 보통 수백 KB 이하예요. transcript나 스크립트 같은 큰 콘텐츠는 별도 API에서 조회하세요.

리소스(Resources)

리소스는 이벤트가 작용할 수 있는 주요 엔터티를 나타내요. 현재 지원되는 항목은 다음과 같아요.
  • Note: 개별 노트 리소스
  • NoteDocument: 노트에서 생성된 템플릿 기반 문서
  • NoteSummary: 노트에 대한 AI 생성 요약
  • FolderNoteRelation: 폴더와 노트 사이의 관계
  • VoiceFileJob: 업로드한 음성 파일의 처리 작업

Webhook Payload 구조

모든 webhook 이벤트는 표준 Event Structure 구조를 따라요.

보안

모든 webhook 요청에는 두 가지 검증 수단이 함께 실려요. 가장 간단한 검증은 Authorization 헤더의 secret을 설정해 둔 값과 비교하는 것이에요. 더 강한 검증이 필요하면 X-Tiro-Signature 헤더의 HMAC-SHA256 서명을 확인하세요 — secret 자체를 비교하지 않고도 요청 진위와 본문 변조 여부를 함께 확인할 수 있어요.

검증 예시

전달 & 재시도

  • Method: HTTP POST
  • Content-Type: application/json
  • Timeout: 60초
  • Retries: exponential backoff로 최대 5회 재시도 (총 6회 시도)
  • Success: 모든 2xx HTTP 상태 코드

재시도 스케줄

  1. 15초
  2. 30초
  3. 5분
  4. 30분
  5. 2시간

시작하기

  1. endpoint 마련: POST 요청을 받을 수 있는 HTTP endpoint를 만들어요
  2. webhook 설정: Tiro Platform에서 webhook endpoint를 등록해요
  3. 이벤트 처리: 애플리케이션에서 들어오는 webhook payload를 처리해요
Webhook endpoint는 워크스페이스 단위로 등록/관리돼요. Platform에서 endpoint를 추가하면 현재 워크스페이스의 이벤트가 그 endpoint로 전달돼요. 여러 워크스페이스를 운영한다면 워크스페이스마다 endpoint를 등록하고, payload 최상위의 workspaceGuid로 이벤트 출처를 구분하세요.
노트 이벤트(note.*, note_summary.*, note_document.*)는 워크스페이스 전체 구성원에게 공유된 폴더의 노트만 발송해요. 개인 폴더의 노트나 어느 폴더에도 넣지 않은 노트는 이벤트가 발송되지 않아요. 폴더 이벤트(folder.note.*)와 음성 파일 작업 이벤트는 이 범위가 적용되지 않아요. 이 범위가 적용되기 전에 등록한 endpoint는 당분간 예전처럼 동작하고, 차례로 전환될 예정이에요. 자세한 범위는 시스템 키가 조회하는 노트 범위를 참고하세요.
조직(Organization) 계약을 사용 중이라면 조직 단위 webhook도 등록할 수 있어요. 조직 endpoint는 조직 소속 워크스페이스 전체의 이벤트를 워크스페이스 구분 없이 받고, payload에 organizationGuid가 포함돼요. 자세한 내용은 조직 단위로 연동하기를 참고하세요.
엔드포인트를 등록한 뒤 Event StructureBest Practices를 확인하세요.