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

> Review the common Tiro webhook payload, supported event types, resource mappings, and implementation details for reliable event handling.

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

## Overview

All webhook events follow a consistent payload structure. This document describes the standard format used across all event types.

## Standard Event Structure

<Json data={EventBaseStructure} />

## Field Descriptions

### Top-Level Fields

<ParamField body="id" type="string" required>
  Unique identifier for this webhook event. Use this for idempotency and deduplication.
</ParamField>

<ParamField body="type" type="string" required>
  Event type identifier (e.g., `note.created`, `note.recording.completed`).
</ParamField>

<ParamField body="createdAt" type="string" required>
  ISO-8601 timestamp when the event occurred. Use this for event ordering.
</ParamField>

<ParamField body="workspaceGuid" type="string">
  GUID of the workspace the event belongs to. Use this to tell sources apart when one endpoint receives events from several workspaces. `null` when the event is not associated with a workspace.
</ParamField>

<ParamField body="data" type="object" required>
  Event-specific data containing resource information.
</ParamField>

### Data Object Fields

<ParamField body="data.resourceType" type="string" required>
  The type of resource that triggered the event. Examples: `Note`, `NoteDocument`, `NoteSummary`, `FolderNoteRelation`.
</ParamField>

<ParamField body="data.resourceId" type="string" required>
  Unique identifier for the specific resource instance. Use this for quick routing and idempotency.
</ParamField>

<ParamField body="data.resource" type="object" required>
  The actual resource data. Structure depends on the resource type and follows Tiro's standard schemas.
</ParamField>

## Event Types

Event types identify the specific action that occurred. Here are some examples:

```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"
```

## What data does a Voice File Job event include?

The `data.resource` object for a `voice_file_job.*` event contains job metadata only. Webhooks do not include uploaded audio or transcript text.

| Field                | Type           | Description                                                             |
| -------------------- | -------------- | ----------------------------------------------------------------------- |
| `id`                 | string         | Voice File Job ID.                                                      |
| `workspaceGuid`      | string         | GUID of the workspace that owns the job.                                |
| `status`             | string         | Job status after the event. The deleted event uses `DELETED`.           |
| `processCompletedAt` | string \| null | Time when processing completed or failed. `null` before either outcome. |
| `errorMessage`       | string \| null | Failure reason. `null` for events other than failure.                   |

## Resource Type Mapping

| Event Type         | Resource Type        | Schema Reference                                                           |
| ------------------ | -------------------- | -------------------------------------------------------------------------- |
| `note.*`           | `Note`               | [Note API](/api-reference/note/get-note)                                   |
| `note_document.*`  | `NoteDocument`       | [NoteDocument Events](/en/developers/webhooks/events/note-document-events) |
| `note_summary.*`   | `NoteSummary`        | [NoteSummary Events](/en/developers/webhooks/events/note-summary-events)   |
| `folder.*`         | `FolderNoteRelation` | [FolderNote Events](/en/developers/webhooks/events/folder-note-events)     |
| `voice_file_job.*` | `VoiceFileJob`       | [Voice File overview](/en/developers/voice-file/overview)                  |