Skip to main content Home Skills Automation & Agents twinmind-webhooks-events twinmind-webhooks-events jeremylongshore
Handle TwinMind webhooks and events for real-time meeting notifications.
Use when implementing webhook handlers, processing meeting events,
or building real-time integrations.
Trigger with phrases like "twinmind webhooks", "twinmind events",
"twinmind notifications", "meeting webhook handler".
bunx add-skill jeremylongshore/claude-code-plugins-plus-skills -s twinmind-webhooks-events ai automation claude-code devops marketplace mcp
TwinMind Webhooks & Events
Overview
Implement webhook handlers for real-time TwinMind meeting events and notifications.
Prerequisites
TwinMind Pro/Enterprise account
Public HTTPS endpoint for webhooks
Webhook secret configured
Understanding of event-driven architecture
Instructions
Step 1: Define Event Types
// src/twinmind/events/types.ts
export enum TwinMindEventType {
// Transcription events
TRANSCRIPTION_STARTED = 'transcription.started',
TRANSCRIPTION_COMPLETED = 'transcription.completed',
TRANSCRIPTION_FAILED = 'transcription.failed',
// Meeting events
MEETING_STARTED = 'meeting.started',
MEETING_ENDED = 'meeting.ended',
MEETING_PARTICIPANT_JOINED = 'meeting.participant.joined',
MEETING_PARTICIPANT_LEFT = 'meeting.participant.left',
// Summary events
SUMMARY_GENERATED = 'summary.generated',
ACTION_ITEMS_EXTRACTED = 'action_items.extracted',
// Calendar events
CALENDAR_SYNCED = 'calendar.synced',
CALENDAR_EVENT_REMINDER = 'calendar.event.reminder',
// Account events
USAGE_LIMIT_WARNING = 'usage.limit.warning',
USAGE_LIMIT_EXCEEDED = 'usage.limit.exceeded',
}
export interface TwinMindEvent<T = any> {
id: string;
type: TwinMindEventType;
created_at: string;
data: T;
}
export interface TranscriptionCompletedData {
transcript_id: string;
duration_seconds: number;
language: string;
word_count: number;
speaker_count: number;
model: string;
}
export interface MeetingEndedData {
meeting_id: string;
transcript_id: string;
title: string;
duration_seconds: number;
participants: string[];
summary_available: boolean;
}
export interface SummaryGeneratedData {
summary_id: string;
transcript_id: string;
action_item_count: number;
key_point_count: number;
}
export interface ActionItemsExtractedData {
transcript_id: string;
action_items: Array<{
text: string;
assignee?: string;
due_date?: string;
}>;
}
Step 2: Implement Webhook Handler // src/twinmind/webhooks/handler.ts
import crypto from 'crypto';
import express, { Request, Response, NextFunction } from 'express';
import { TwinMindEvent, TwinMindEventType } from '../events/types';
// Signature verification middleware
export function verifySignature(
req: Request,
res: Response,
next: NextFunction
): void {
const signature = req.headers['x-twinmind-signature'] as string;
const timestamp = req.headers['x-twinmind-timestamp'] as string;
const secret = process.env.TWINMIND_WEBHOOK_SECRET!;
if (!signature || !timestamp) {
res.status(401).json({ error: 'Missing signature or timestamp' });
return;
}
// Check timestamp to prevent replay attacks (5 minute window)
const timestampMs = parseInt(timestamp) * 1000;
const now = Date.now();
if (Math.abs(now - timestampMs) > 5 * 60 * 1000) {
res.status(401).json({ error: 'Request too old' });
return;
}
// Verify signature
const payload = `${timestamp}.${JSON.stringify(req.body)}`;
const expectedSignature = crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex');
if (!crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(`sha256=${expectedSignature}`)
)) {
res.status(401).json({ error: 'Invalid signature' });
return;
}
next();
}
// Event handlers registry
type EventHandler<T = any> = (event: TwinMindEvent<T>) => Promise<void>;
const handlers = new Map<TwinMindEventType, EventHandler[]>();
export function registerHandler<T>(
eventType: TwinMindEventType,
handler: EventHandler<T>
): void {
const existing = handlers.get(eventType) || [];
existing.push(handler);
handlers.set(eventType, existing);
}
// Main webhook route handler
export async function handleWebhook(
req: Request,
res: Response
): Promise<void> {
const event = req.body as TwinMindEvent;
console.log(`Received event: ${event.type} (${event.id})`);
// Acknowledge receipt immediately
res.status(200).json({ received: true, event_id: event.id });
// Process event asynchronously
try {
const eventHandlers = handlers.get(event.type as TwinMindEventType);
if (eventHandlers && eventHandlers.length > 0) {
await Promise.all(
eventHandlers.map(handler => handler(event))
);
} else {
console.log(`No handlers registered for event type: ${event.type}`);
}
} catch (error) {
console.error(`Error processing event ${event.id}:`, error);
// Don't throw - we already acknowledged receipt
}
}
Step 3: Implement Event Handlers // src/twinmind/webhooks/event-handlers.ts
import {
TwinMindEvent,
TwinMindEventType,
TranscriptionCompletedData,
MeetingEndedData,
SummaryGeneratedData,
ActionItemsExtractedData,
} from '../events/types';
import { registerHandler } from './handler';
import { notifySlack, sendEmail } from '../notifications';
import { createTasksInLinear } from '../integrations/linear';
// Handle transcription completed
registerHandler<TranscriptionCompletedData>(
TwinMindEventType.TRANSCRIPTION_COMPLETED,
async (event) => {
const { transcript_id, duration_seconds, word_count, speaker_count } = event.data;
console.log(`Transcription completed: ${transcript_id}`);
console.log(` Duration: ${duration_seconds}s`);
console.log(` Words: ${word_count}`);
console.log(` Speakers: ${speaker_count}`);
// Trigger summary generation
const client = getTwinMindClient();
await client.post('/summarize', { transcript_id });
}
);
// Handle meeting ended
registerHandler<MeetingEndedData>(
TwinMindEventType.MEETING_ENDED,
async (event) => {
const { meeting_id, title, duration_seconds, participants, summary_available } = event.data;
console.log(`Meeting ended: ${title} (${meeting_id})`);
// Notify participants
await notifySlack({
channel: '#meetings',
message: `Meeting "${title}" has ended (${Math.round(duration_seconds / 60)} minutes)`,
participants,
});
// If summary is ready, send it
if (summary_available) {
const client = getTwinMindClient();
const summary = await client.get(`/summaries/${event.data.transcript_id}`);
await sendEmail({
to: participants,
subject: `Meeting Summary: ${title}`,
body: summary.data.summary,
});
}
}
);
// Handle summary generated
registerHandler<SummaryGeneratedData>(
TwinMindEventType.SUMMARY_GENERATED,
async (event) => {
const { summary_id, transcript_id, action_item_count } = event.data;
console.log(`Summary generated: ${summary_id}`);
console.log(` Action items: ${action_item_count}`);
// Store summary in database
await db.summaries.create({
id: summary_id,
transcript_id,
created_at: new Date(event.created_at),
});
}
);
// Handle action items extracted
registerHandler<ActionItemsExtractedData>(
TwinMindEventType.ACTION_ITEMS_EXTRACTED,
async (event) => {
const { transcript_id, action_items } = event.data;
console.log(`Action items extracted: ${action_items.length}`);
// Create tasks in project management tool
if (action_items.length > 0) {
await createTasksInLinear(action_items);
}
}
);
// Handle usage warning
registerHandler(
TwinMindEventType.USAGE_LIMIT_WARNING,
async (event) => {
console.warn('Usage limit warning:', event.data);
await notifySlack({
channel: '#alerts',
message: `:warning: TwinMind usage at ${event.data.percent_used}% of limit`,
});
}
);
Step 4: Set Up Webhook Endpoint // src/api/webhooks/twinmind.ts
import express from 'express';
import { verifySignature, handleWebhook } from '../../twinmind/webhooks/handler';
const router = express.Router();
// Raw body parser for signature verification
router.use(express.json({
verify: (req: any, res, buf) => {
req.rawBody = buf;
}
}));
// Webhook endpoint
router.post(
'/twinmind',
verifySignature,
handleWebhook
);
export default router;
Step 5: Register Webhooks // scripts/register-webhooks.ts
import { getTwinMindClient } from '../src/twinmind/client';
import { TwinMindEventType } from '../src/twinmind/events/types';
async function registerWebhooks() {
const client = getTwinMindClient();
const webhookUrl = process.env.WEBHOOK_BASE_URL + '/webhooks/twinmind';
// Register webhook
const response = await client.post('/webhooks', {
url: webhookUrl,
events: [
TwinMindEventType.TRANSCRIPTION_COMPLETED,
TwinMindEventType.MEETING_ENDED,
TwinMindEventType.SUMMARY_GENERATED,
TwinMindEventType.ACTION_ITEMS_EXTRACTED,
TwinMindEventType.USAGE_LIMIT_WARNING,
],
enabled: true,
});
console.log('Webhook registered:', response.data);
// Generate and store webhook secret
console.log('Webhook Secret:', response.data.secret);
console.log('Add to .env: TWINMIND_WEBHOOK_SECRET=' + response.data.secret);
}
registerWebhooks();
Step 6: Implement Retry Logic for Failed Events // src/twinmind/webhooks/retry.ts
import { TwinMindEvent } from '../events/types';
interface FailedEvent {
event: TwinMindEvent;
attempts: number;
lastError: string;
nextRetry: Date;
}
class WebhookRetryQueue {
private queue: FailedEvent[] = [];
private maxRetries = 5;
private baseDelayMs = 60000; // 1 minute
async add(event: TwinMindEvent, error: Error): Promise<void> {
const existing = this.queue.find(f => f.event.id === event.id);
if (existing) {
existing.attempts += 1;
existing.lastError = error.message;
existing.nextRetry = new Date(
Date.now() + this.baseDelayMs * Math.pow(2, existing.attempts)
);
if (existing.attempts >= this.maxRetries) {
// Move to dead letter queue
await this.moveToDeadLetter(existing);
this.queue = this.queue.filter(f => f.event.id !== event.id);
}
} else {
this.queue.push({
event,
attempts: 1,
lastError: error.message,
nextRetry: new Date(Date.now() + this.baseDelayMs),
});
}
}
async processRetries(): Promise<void> {
const now = new Date();
const readyEvents = this.queue.filter(f => f.nextRetry <= now);
for (const failedEvent of readyEvents) {
try {
await this.reprocessEvent(failedEvent.event);
this.queue = this.queue.filter(f => f.event.id !== failedEvent.event.id);
console.log(`Successfully reprocessed event: ${failedEvent.event.id}`);
} catch (error: any) {
await this.add(failedEvent.event, error);
}
}
}
private async reprocessEvent(event: TwinMindEvent): Promise<void> {
// Re-dispatch to handlers
const handlers = getHandlersForEvent(event.type);
await Promise.all(handlers.map(h => h(event)));
}
private async moveToDeadLetter(failedEvent: FailedEvent): Promise<void> {
console.error(`Event ${failedEvent.event.id} moved to dead letter queue after ${failedEvent.attempts} attempts`);
// Store in database for manual review
await db.deadLetterQueue.create({
event_id: failedEvent.event.id,
event_type: failedEvent.event.type,
payload: failedEvent.event,
attempts: failedEvent.attempts,
last_error: failedEvent.lastError,
});
// Alert ops team
await notifySlack({
channel: '#alerts',
message: `:x: Webhook event failed after ${failedEvent.attempts} attempts: ${failedEvent.event.id}`,
});
}
}
export const retryQueue = new WebhookRetryQueue();
// Start retry processor
setInterval(() => retryQueue.processRetries(), 60000);
Output
Event type definitions
Webhook handler with signature verification
Event processing logic
Webhook registration script
Retry queue for failed events
Webhook Events Reference Event Description Data transcription.startedTranscription job started transcript_id, audio_urltranscription.completedTranscription finished transcript_id, duration, word_counttranscription.failedTranscription failed transcript_id, errormeeting.startedLive meeting capture started meeting_id, titlemeeting.endedMeeting finished meeting_id, transcript_id, participantssummary.generatedAI summary ready summary_id, action_item_countaction_items.extractedAction items available transcript_id, action_items[]usage.limit.warningUsage approaching limit percent_used, limit
Error Handling Issue Cause Solution Invalid signature Wrong secret Verify webhook secret Event missed Endpoint down Implement retry queue Processing slow Heavy handler Use async queue Duplicate events Retries Implement idempotency
Resources
Next Steps For performance optimization, see twinmind-performance-tuning.
