What is a webhook endpoint?
A webhook endpoint is a URL where Tiro sends an HTTP POST request when an event occurs. Register it in Tiro Platform and you receive events without polling the API.How Webhooks Work
- Configure: Set up a webhook endpoint in your application
- Register: Add your endpoint to receive the events you care about
- Receive: Get instant notifications when events occur
- Process: Handle the event data in your application
Event & Resource Structure
Webhooks are organized around Events and Resources:Events
Events represent actions that occur in your workspace. See Note Events, Note Document Events, Note Summary Events, FolderNote Events, and Voice File API overview for detailed information. Webhook events carry metadata only and usually stay under a few hundred KB. Retrieve large content such as transcripts and scripts from the separate APIs.Resources
Resources represent the main entities that events can act upon.Note: Individual note resourcesNoteDocument: Template-based documents generated from notesNoteSummary: AI-generated summaries for notesFolderNoteRelation: Relationship between folders and notes
Webhook Payload Structure
All webhook events follow the standard Event Structure structure:Security
Webhook requests are authenticated using your secret key in the Authorization header:Verification Example
Delivery & Retries
- Method: HTTP POST
- Content-Type:
application/json - Timeout: 60 seconds
- Retries: Up to 5 retries (6 total attempts) with exponential backoff
- Success: Any 2xx HTTP status code
Retry Schedule
- 15 seconds
- 30 seconds
- 5 minutes
- 30 minutes
- 2 hours
Getting Started
- Set up your endpoint: Create an HTTP endpoint that can receive POST requests
- Configure webhooks: Register your webhook endpoint in Tiro Platform
- Handle events: Process incoming webhook payloads in your application
A Account webhook is one endpoint tied to a user account. It fans in events from every workspace the user can currently access. Note, summary, document, and folder events are delivered for resources the user can access. Use the top-level
workspaceGuid in the payload to tell which workspace produced an event.A Workspace webhook is registered and managed per workspace and receives events from its one bound workspace. Note events (
note.*, note_summary.*, note_document.*) and folder events (folder.note.*) are delivered only for notes in folders shared with all workspace members. A note in a private folder, a note in a folder shared with only some members, or a note that sits in no folder at all produces no events. Voice file job events are outside this scope. System endpoints registered before this scope took effect keep their previous behavior for now, and are being moved over in stages. For the full read scope, see What notes a system API key reads.If you are on an Organization contract, you can also register an organization-level webhook. An organization endpoint receives events from every workspace in the organization without distinguishing between them, and the payload includes
organizationGuid. See Integrating at the organization level for details.