Skip to main content

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

  1. Configure: Set up a webhook endpoint in your application
  2. Register: Add your endpoint to receive the events you care about
  3. Receive: Get instant notifications when events occur
  4. 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 resources
  • NoteDocument: Template-based documents generated from notes
  • NoteSummary: AI-generated summaries for notes
  • FolderNoteRelation: 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:
The secret key is provided when you configure your webhook endpoint and is used to verify the authenticity of incoming requests. Simply compare the provided secret with your configured secret to verify authenticity.

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

  1. 15 seconds
  2. 30 seconds
  3. 5 minutes
  4. 30 minutes
  5. 2 hours

Getting Started

  1. Set up your endpoint: Create an HTTP endpoint that can receive POST requests
  2. Configure webhooks: Register your webhook endpoint in Tiro Platform
  3. Handle events: Process incoming webhook payloads in your application
Configure your webhook endpoint at Tiro Platform.
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.
After registering your endpoint, review the Event Structure and Best Practices.