Skip to main content

​
What are Webhooks?

Webhooks allow your application to receive real-time notifications when events occur in your workspace. Instead of polling our API for changes, we’ll send HTTP POST requests to your specified endpoint whenever something happens.

​
How Webhooks Work

  1. Configure: Set up a webhook endpoint in your application
  2. Subscribe: Register your endpoint with us to receive specific events
  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 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
  • FolderNoteRelation: Relationship between folders and notes

​
Webhook Payload Structure

All webhook events follow the standard Event Structure structure: 
{
  "id": "evt_01J9ABCDEF",
  "type": "note.created",
  "createdAt": "2025-09-05T07:12:34Z",
  "data": {
    "resourceType": "Note",
    "resourceId": "1Lvbn2EQKmQvV",
    "resource": {
      "title": "Meeting Note"
    }
  }
}

​
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 6 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: Use our API to register your webhook endpoint
  3. Handle events: Process incoming webhook payloads in your application
  4. Test: Test webhook feature is coming soon

​
Next Steps

Event Structure

Standard webhook event payload structure.

Best Practices

Guidelines for handling webhook events.

Note Events

Detailed documentation for note-related events.

FolderNote Events

Detailed documentation for FolderNoteRelation events.