Webhooks

Webhooks allow you to receive real-time notifications when events occur in the platform. Set up webhooks to integrate with external systems, trigger automations, or keep your systems synchronized.

Webhook Setup

Create a webhook endpoint:

1. Navigate to Settings → Webhooks
2. Click "Create Webhook"
3. Enter webhook URL (must be HTTPS)
4. Select events to subscribe to
5. Configure webhook settings
6. Test the webhook
7. Save the webhook

Webhook Configuration:

• URL: HTTPS endpoint to receive webhook payloads
• Events: Select which events trigger the webhook
• Secret: Optional secret for verifying webhook authenticity
• Active Status: Enable or disable the webhook
• Retry Policy: Configure retry behavior for failed deliveries

Webhook Events

Subscribe to platform events:

Recording Events:

• recording.created: New recording uploaded
• recording.processing.started: Recording processing began
• recording.processing.completed: Recording processing finished
• recording.processing.failed: Recording processing failed
• recording.transcript.ready: Transcript available
• recording.deleted: Recording deleted

Meeting Events:

• meeting.created: New meeting created
• meeting.updated: Meeting details updated
• meeting.deleted: Meeting deleted
• meeting.started: Meeting started
• meeting.ended: Meeting ended

Transcript Events:

• transcript.generated: Transcript generated
• transcript.updated: Transcript updated

Signal Events:

• signal.detected: New signal detected
• signal.confirmed: Signal confirmed by user

User Events:

• user.invited: Team member invited
• user.joined: Team member joined organization

Select only the events you need to reduce webhook traffic.

Webhook Payloads

Webhook payloads contain event information:

Example Payload:

{
  "event": "recording.processing.completed",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "recording": {
      "id": 123,
      "title": "Team Meeting",
      "status": "completed",
      "duration": 3600,
      "transcript_ready": true
    }
  }
}

Recording Created Payload:

{
  "event": "recording.created",
  "timestamp": "2024-01-15T10:00:00Z",
  "data": {
    "recording": {
      "id": 123,
      "title": "New Recording",
      "status": "new",
      "file_size": 104857600,
      "created_at": "2024-01-15T10:00:00Z"
    }
  }
}

Transcript Ready Payload:

{
  "event": "recording.transcript.ready",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "recording": {
      "id": 123,
      "title": "Team Meeting",
      "transcript": {
        "id": 456,
        "text": "Full transcript text...",
        "speakers": [
          {
            "id": 1,
            "name": "John Doe"
          }
        ]
      }
    }
  }
}

All webhook payloads include:

• event: Event type identifier
• timestamp: ISO 8601 timestamp
• data: Event-specific data

Webhook Security

Secure your webhooks:

Signature Verification:

Webhooks include a signature header for verification:

X-Webhook-Signature: sha256=abc123def456...

Verification Example (Node.js):

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(JSON.stringify(payload)).digest('hex');
  const expectedSignature = `sha256=${digest}`;
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// In your webhook handler
const signature = req.headers['x-webhook-signature'];
const isValid = verifyWebhookSignature(req.body, signature, webhookSecret);

if (!isValid) {
  return res.status(401).send('Invalid signature');
}

Security Best Practices:

• Always use HTTPS for webhook URLs
• Verify webhook signatures
• Use webhook secrets
• Implement idempotency (handle duplicate events)
• Rate limit webhook processing
• Log all webhook deliveries

Webhook Testing

Test your webhook endpoints:

Test Webhook:

1. Open webhook settings
2. Click "Test Webhook"
3. Select event type to test
4. Send test payload
5. Verify receipt at your endpoint

Manual Testing:

Use tools like ngrok to test webhooks locally:

# Start ngrok tunnel
ngrok http 3000

# Use ngrok URL as webhook URL
# https://abc123.ngrok.io/webhooks

Test Payload Example:

{
  "event": "recording.created",
  "timestamp": "2024-01-15T10:00:00Z",
  "data": {
    "recording": {
      "id": 999,
      "title": "Test Recording",
      "status": "new"
    }
  }
}

Webhook Delivery Status:

• Monitor webhook delivery status
• View delivery logs
• Check success/failure rates
• Review error messages
• Retry failed deliveries

Best Practices

Follow these best practices to get the most out of the API:

API Usage

• Use Appropriate Authentication: Choose the right auth method for your use case
• Handle Errors Gracefully: Implement proper error handling and retry logic
• Respect Rate Limits: Implement exponential backoff when hitting limits
• Cache When Possible: Cache responses to reduce API calls
• Use Pagination: Always paginate large result sets
• Monitor Usage: Track API usage and costs

Security

• Secure Credentials: Never commit API keys or secrets to version control
• Use Environment Variables: Store credentials in environment variables
• Rotate Credentials: Regularly rotate API keys and client secrets
• Verify Webhooks: Always verify webhook signatures
• Use HTTPS: Always use HTTPS for API requests
• Principle of Least Privilege: Grant only necessary permissions

Performance

• Batch Requests: Use batch operations when possible
• Optimize Queries: Request only needed fields in GraphQL
• Use Webhooks: Prefer webhooks over polling when possible
• Implement Caching: Cache frequently accessed data
• Connection Pooling: Reuse HTTP connections

Development

• Use SDKs: Use official SDKs when available
• Version Control: Pin API versions in your code
• Testing: Test integrations thoroughly before production
• Documentation: Document your API usage
• Error Logging: Log API errors for debugging

Next Steps

Now that you understand the API:

• Explore the API: Use the GraphQL playground or REST API explorer
• Build Integrations: Create custom integrations for your workflow
• Set Up Webhooks: Configure webhooks for real-time updates
• Review Examples: Check out code examples and tutorials
• Join Community: Connect with other developers using the API

Need Help?

• API Documentation: Browse complete API reference documentation
• GraphQL Playground: Explore the API interactively
• Code Examples: Review code examples in multiple languages
• Support: Contact API support for assistance
• Status Page: Check API status and uptime
• Community Forum: Get help from the developer community

Happy coding! 🚀