Skip to main content

Documentation Index

Fetch the complete documentation index at: https://api-docs.tiro.ooo/llms.txt

Use this file to discover all available pages before exploring further.

​
What are Webhooks?

Webhooks allow your application to receive real-time notifications when events occur in your workspace. Instead of polling the API, Tiro sends HTTP POST requests to your endpoint whenever something happens.

​
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, and FolderNote Events for detailed information. Webhook events are designed to stay under several hundred KB by including only metadata. Large content like transcripts and scripts are accessed via separate APIs to ensure webhook reliability and performance.

​
Resources

Resources represent the main entities that events can act upon. Currently supported:
  • 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: 
Authorization: Bearer {secret_key}
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

function verifyWebhookAuth(authHeader, expectedSecret) {
  const token = authHeader.replace('Bearer ', '');
  return token === expectedSecret;
}

// Usage in your webhook endpoint
app.post('/webhooks/tiro', (req, res) => {
  const authHeader = req.headers.authorization;
  
  if (!verifyWebhookAuth(authHeader, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Unauthorized');
  }
  
  // Process webhook event
  const event = req.body;
  handleWebhookEvent(event);
  
  res.status(200).send('OK');
});

​
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. With your endpoint registered, get familiar with the Event Structure you’ll receive — then read Best Practices to handle retries, idempotency, and signature verification before you go live.