> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tiro.ooo/llms.txt
> Use this file to discover all available pages before exploring further.

# Event Structure

> Tiro 웹훅 이벤트의 공통 페이로드 구조, 지원 이벤트 타입, 리소스 매핑을 구현 예시와 함께 확인하세요.

export const EventBaseStructure = {
  id: "evt_01J9ABCDEF",
  type: "note.created",
  createdAt: "2025-09-05T07:12:34Z",
  workspaceGuid: "ws_a1b2c3d4",
  data: {
    resourceType: "Note",
    resourceId: "note-guid-123",
    resource: {
      "title": "Meeting Note"
    }
  }
};

export const Json = ({data, lang = 'json', spaces = 2}) => <pre>
    <code className={`language-${lang}`}>{JSON.stringify(data, null, spaces)}</code>
  </pre>;

## 개요

모든 웹훅 이벤트는 일관된 페이로드 구조를 따라요. 이 문서는 모든 이벤트 타입에 공통으로 사용되는 표준 형식을 설명해요.

## 표준 Event Structure

<Json data={EventBaseStructure} />

## 필드 설명

### 최상위 필드

<ParamField body="id" type="string" required>
  이 webhook 이벤트의 고유 식별자예요. idempotency와 중복 제거에 사용하세요.
</ParamField>

<ParamField body="type" type="string" required>
  이벤트 타입 식별자예요 (예: `note.created`, `note.recording.completed`).
</ParamField>

<ParamField body="createdAt" type="string" required>
  이벤트가 발생한 시각의 ISO-8601 timestamp예요. 이벤트 정렬에 사용하세요.
</ParamField>

<ParamField body="workspaceGuid" type="string">
  이벤트가 속한 워크스페이스의 GUID예요. 하나의 endpoint가 여러 워크스페이스의 이벤트를 받을 때 출처를 구분하는 데 사용하세요. 이벤트가 워크스페이스에 연결되지 않은 경우 `null`이에요.
</ParamField>

<ParamField body="data" type="object" required>
  리소스 정보를 담고 있는 이벤트별 데이터예요.
</ParamField>

### Data 오브젝트 필드

<ParamField body="data.resourceType" type="string" required>
  이벤트를 발생시킨 리소스의 타입이에요. 예: `Note`, `NoteDocument`, `NoteSummary`, `FolderNoteRelation`.
</ParamField>

<ParamField body="data.resourceId" type="string" required>
  특정 리소스 인스턴스의 고유 식별자예요. 빠른 라우팅과 idempotency에 사용하세요.
</ParamField>

<ParamField body="data.resource" type="object" required>
  실제 리소스 데이터예요. 구조는 리소스 타입에 따라 달라지며 Tiro의 표준 스키마를 따라요.
</ParamField>

## 이벤트 타입

이벤트 타입은 발생한 특정 동작을 식별해요. 다음은 몇 가지 예시예요.

```json theme={"system"}
"note.created"
"note.deleted"
"note.user_content.updated"
"note.recording.completed"
"note.ended"
"note.participants.updated"
"note_document.generated"
"note_document.updated"
"note_document.deleted"
"note_summary.generated"
"note_summary.updated"
"note_summary.deleted"
"folder.note.added"
"folder.note.removed"
"voice_file_job.created"
"voice_file_job.completed"
"voice_file_job.failed"
"voice_file_job.deleted"
```

## Voice File Job 이벤트에는 어떤 데이터가 포함되나요?

`voice_file_job.*` 이벤트의 `data.resource`는 작업 메타데이터만 담아요. Tiro는 오디오와 전사 본문을 웹훅으로 전송하지 않아요.

| 필드                   | 타입             | 설명                                           |
| -------------------- | -------------- | -------------------------------------------- |
| `id`                 | string         | Voice File Job ID예요.                         |
| `workspaceGuid`      | string         | 작업이 속한 워크스페이스 GUID예요.                        |
| `status`             | string         | 이벤트 발생 뒤의 상태예요. 삭제 이벤트에서는 `DELETED`예요.       |
| `processCompletedAt` | string \| null | 처리를 완료했거나 실패한 시각이에요. 아직 완료하지 않았으면 `null`이에요. |
| `errorMessage`       | string \| null | 실패 이유예요. 실패 이벤트가 아니면 `null`이에요.              |

## 리소스 타입 매핑

| Event Type         | Resource Type        | Schema Reference                                                           |
| ------------------ | -------------------- | -------------------------------------------------------------------------- |
| `note.*`           | `Note`               | [Note API](/api-reference/note/get-note)                                   |
| `note_document.*`  | `NoteDocument`       | [NoteDocument Events](/ko/developers/webhooks/events/note-document-events) |
| `note_summary.*`   | `NoteSummary`        | [NoteSummary Events](/ko/developers/webhooks/events/note-summary-events)   |
| `folder.*`         | `FolderNoteRelation` | [FolderNote Events](/ko/developers/webhooks/events/folder-note-events)     |
| `voice_file_job.*` | `VoiceFileJob`       | [음성 파일 API 개요](/ko/developers/voice-file/overview)                         |