---
name: twinmind-webhooks-events-b0155267e8dc
description: |
  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".
allowed-tools: Read, Write, Edit, Bash(npm:*), Grep
version: 1.0.0
license: MIT
author: Jeremy Longshore <jeremy@intentsolutions.io>
---

# 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

```typescript
// 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

```typescript
// 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

```typescript
// 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

```typescript
// 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

```typescript
// 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

```typescript
// 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.started` | Transcription job started | `transcript_id`, `audio_url` |
| `transcription.completed` | Transcription finished | `transcript_id`, `duration`, `word_count` |
| `transcription.failed` | Transcription failed | `transcript_id`, `error` |
| `meeting.started` | Live meeting capture started | `meeting_id`, `title` |
| `meeting.ended` | Meeting finished | `meeting_id`, `transcript_id`, `participants` |
| `summary.generated` | AI summary ready | `summary_id`, `action_item_count` |
| `action_items.extracted` | Action items available | `transcript_id`, `action_items[]` |
| `usage.limit.warning` | Usage 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
- [TwinMind Webhooks API](https://twinmind.com/docs/webhooks)
- [Webhook Best Practices](https://twinmind.com/docs/webhook-best-practices)
- [Event Reference](https://twinmind.com/docs/events)

## Next Steps
For performance optimization, see `twinmind-performance-tuning`.


---
Source attribution: Dicklesworthstone
Original project: https://github.com/Dicklesworthstone/pi_agent_rust/blob/f28fc46ee0db8e710d95b8b55592cd38d60f2b26/tests/ext_conformance/artifacts/plugins-community/plugins/saas-packs/twinmind-pack/skills/twinmind-webhooks-events/SKILL.md
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Mega AI Hub.

## Upstream license notice

MIT License (with OpenAI/Anthropic Rider)

Copyright (c) 2026 Jeffrey Emanuel

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

ADDITIONAL RIDER / RESTRICTION (OpenAI / Anthropic):

This rider is part of the "conditions" of this License. In the event of any
conflict between this rider and any other portion of this License, this rider
controls.

"Restricted Parties" means OpenAI, L.L.C.; Anthropic, PBC; any of their
respective Affiliates; and any person or entity acting directly or indirectly
on behalf of, for the benefit of, or under the direction of any of the
foregoing (including any officer, director, employee, contractor, agent,
consultant, service provider, or representative).

Notwithstanding any other provision of this License, no rights are granted to
any Restricted Party. Any purported license, sublicense, assignment, transfer,
or other permission to any Restricted Party is null and void absent the
express prior written permission of Jeffrey Emanuel.

You may not provide, disclose, distribute, sublicense, sell, lease, lend,
host, make available, or otherwise permit access to the Software or any
derivative work of the Software (as defined in applicable copyright law)
(collectively, "Derivative Works") to or for any Restricted Party.

For purposes of this rider, "use" includes, without limitation: copying,
modifying, merging, publishing, distributing, sublicensing, selling,
transferring, making available, hosting, deploying, executing, benchmarking,
testing, analyzing, indexing, or incorporating the Software or any Derivative
Works into any dataset, training corpus, evaluation harness, or pipeline for
machine learning or other automated systems.

This rider applies to the Software and all Derivative Works. As a condition of
use, you agree that this rider is a precondition to exercising any rights
under this License, and you agree that any distribution of the Software or any
Derivative Works must include this rider provision unmodified.

Any breach of this rider automatically and immediately terminates the
permissions granted by this License. Upon termination, you must immediately
cease all use and distribution of the Software and any Derivative Works and
destroy all copies under your control.

You agree that a breach of this rider would cause irreparable harm and that
Jeffrey Emanuel may seek injunctive or other equitable relief to enforce this
rider, in addition to any other remedies available at law. To the maximum
extent permitted by applicable law, the prevailing party in any action to
enforce this rider shall be entitled to recover reasonable attorneys' fees and
costs.

For purposes of this rider, "Affiliate" means any entity that directly or
indirectly controls, is controlled by, or is under common control with the
specified party. "Control" means ownership of more than 50% of the voting
securities or other ownership interest, or the power to direct management or
policies by contract or otherwise.

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Mega AI Hub resource metadata

Creator / publisher: Dicklesworthstone
Original project: https://github.com/Dicklesworthstone/pi_agent_rust/blob/f28fc46ee0db8e710d95b8b55592cd38d60f2b26/tests/ext_conformance/artifacts/plugins-community/plugins/saas-packs/twinmind-pack/skills/twinmind-webhooks-events/SKILL.md
Attribution basis: Source repository record

Fields of work: Development & Engineering, Product Management
Roles: Backend Developer, Growth Product Manager, Product Manager
Specialties: API
Tools: Twinmind
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: 4d60a031b73413a12075a8ea00e70f3081133667b4996c409dd4cf566339a8bc