> ## 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.

# イベントの構造

> TiroのWebhookイベントで共通するペイロード構造、対応するイベントタイプ、リソースの対応関係、実装時の注意点を説明します。

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>;

## 概要

すべてのWebhookイベントは、一貫したペイロード構造に従います。このページでは、すべてのイベントタイプで共通して使用される標準形式を説明します。

## 標準的なイベントの構造

<Json data={EventBaseStructure} />

## フィールドの説明

### トップレベルのフィールド

<ParamField body="id" type="string" required>
  この webhook イベントの一意な識別子です。冪等性と重複排除のために利用します。
</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 です。1 つの 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>
  特定のリソースインスタンスの一意な識別子です。素早いルーティングと冪等性のために利用します。
</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`には、ジョブのメタデータのみが含まれます。アップロードした音声や文字起こし本文はWebhookに含まれません。

| フィールド                | 型              | 説明                                    |
| -------------------- | -------------- | ------------------------------------- |
| `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](/ja/developers/webhooks/events/note-document-events) |
| `note_summary.*`   | `NoteSummary`        | [NoteSummary Events](/ja/developers/webhooks/events/note-summary-events)   |
| `folder.*`         | `FolderNoteRelation` | [FolderNote Events](/ja/developers/webhooks/events/folder-note-events)     |
| `voice_file_job.*` | `VoiceFileJob`       | [音声ファイルAPIの概要](/ja/developers/voice-file/overview)                         |