Voice Router SDK - Core API / webhooks

webhooks

Webhook normalization module

Provides unified webhook handling across all transcription providers. Automatically detects provider from payload structure and normalizes webhook events to a common format.

Examples

import { WebhookRouter } from '@meeting-baas/sdk';

const router = new WebhookRouter();
const result = router.route(req.body);

if (result.success) {
  console.log('Provider:', result.provider);
  console.log('Event:', result.event);
}

import express from 'express';
import { WebhookRouter } from '@meeting-baas/sdk';

const app = express();
const router = new WebhookRouter();

app.post('/webhooks/transcription', express.json(), (req, res) => {
  const result = router.route(req.body, {
    verification: {
      signature: req.headers['x-signature'] as string,
      secret: process.env.WEBHOOK_SECRET!
    }
  });

  if (!result.success) {
    return res.status(400).json({ error: result.error });
  }

  // Process the normalized event
  if (result.event?.eventType === 'transcription.completed') {
    console.log('Transcription completed:', result.event.data?.id);
  }

  res.status(200).json({ received: true });
});

Classes

AssemblyAIWebhookHandler

AssemblyAI webhook handler

Handles webhook callbacks from AssemblyAI API:

• completed - Transcription completed successfully
• error - Transcription failed with error

AssemblyAI supports webhook signature verification using HMAC-SHA256.

Examples

import { AssemblyAIWebhookHandler } from '@meeting-baas/sdk';

const handler = new AssemblyAIWebhookHandler();

// Validate webhook
const validation = handler.validate(req.body);
if (!validation.valid) {
  return res.status(400).json({ error: validation.error });
}

// Parse webhook
const event = handler.parse(req.body);
if (event.eventType === 'transcription.completed') {
  console.log('Transcript ID:', event.data?.id);
}

// Verify webhook signature
const isValid = handler.verify(req.body, {
  signature: req.headers['x-assemblyai-signature'],
  secret: process.env.ASSEMBLYAI_WEBHOOK_SECRET,
  rawBody: req.rawBody
});

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

Extends

• BaseWebhookHandler

Constructors

Constructor

new AssemblyAIWebhookHandler(): AssemblyAIWebhookHandler

Returns

AssemblyAIWebhookHandler

Inherited from

BaseWebhookHandler.constructor

Methods

createErrorEvent()

protected createErrorEvent(payload, errorMessage): UnifiedWebhookEvent

Helper method to create error response

Parameters

Returns

UnifiedWebhookEvent

Inherited from

BaseWebhookHandler.createErrorEvent

matches()

matches(payload, _options?): boolean

Check if payload matches AssemblyAI webhook format

Parameters

Returns

boolean

Overrides

BaseWebhookHandler.matches

parse()

parse(payload, _options?): UnifiedWebhookEvent

Parse AssemblyAI webhook payload to unified format

Parameters

Returns

UnifiedWebhookEvent

Overrides

BaseWebhookHandler.parse

validate()

validate(payload, options?): WebhookValidation

Validate webhook payload structure

Checks if payload has required fields and correct types

Parameters

Returns

WebhookValidation

Validation result with details

Inherited from

BaseWebhookHandler.validate

verify()

verify(payload, options): boolean

Verify AssemblyAI webhook signature

AssemblyAI uses HMAC-SHA256 for webhook signature verification. The signature is sent in the X-AssemblyAI-Signature header.

Parameters

Returns

boolean

true if signature is valid

Example

const isValid = handler.verify(req.body, {
  signature: req.headers['x-assemblyai-signature'],
  secret: process.env.ASSEMBLYAI_WEBHOOK_SECRET,
  rawBody: req.rawBody // Raw request body as string or Buffer
});

Overrides

BaseWebhookHandler.verify

Properties

provider

readonly provider: TranscriptionProvider = "assemblyai"

Provider name

Overrides

BaseWebhookHandler.provider

AzureWebhookHandler

Azure webhook handler

Handles webhook callbacks from Azure Speech Services API:

• TranscriptionCreated - Transcription job created
• TranscriptionRunning - Transcription is processing
• TranscriptionSucceeded - Transcription completed successfully
• TranscriptionFailed - Transcription failed with error

Azure supports optional webhook signature verification using a shared secret.

Examples

import { AzureWebhookHandler } from '@meeting-baas/sdk';

const handler = new AzureWebhookHandler();

// Validate webhook
const validation = handler.validate(req.body);
if (!validation.valid) {
  return res.status(400).json({ error: validation.error });
}

// Parse webhook
const event = handler.parse(req.body);
console.log('Event type:', event.eventType);
console.log('Action:', event.raw.action);

// Verify webhook signature (if configured in Azure)
const isValid = handler.verify(req.body, {
  signature: req.headers['x-azure-signature'],
  secret: process.env.AZURE_WEBHOOK_SECRET,
  rawBody: req.rawBody
});

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

const event = handler.parse(req.body);

if (event.eventType === 'transcription.completed') {
  // Extract transcription ID from self link
  const transcriptionId = event.data?.id;

  // Fetch full transcript using AzureAdapter.getTranscript(transcriptionId)
  console.log('Transcription completed:', transcriptionId);
}

Extends

• BaseWebhookHandler

Constructors

Constructor

new AzureWebhookHandler(): AzureWebhookHandler

Returns

AzureWebhookHandler

Inherited from

BaseWebhookHandler.constructor

Methods

createErrorEvent()

protected createErrorEvent(payload, errorMessage): UnifiedWebhookEvent

Helper method to create error response

Parameters

Returns

UnifiedWebhookEvent

Inherited from

BaseWebhookHandler.createErrorEvent

matches()

matches(payload, _options?): boolean

Check if payload matches Azure webhook format

Parameters

Returns

boolean

Overrides

BaseWebhookHandler.matches

parse()

parse(payload, _options?): UnifiedWebhookEvent

Parse Azure webhook payload to unified format

Parameters

Returns

UnifiedWebhookEvent

Overrides

BaseWebhookHandler.parse

validate()

validate(payload, options?): WebhookValidation

Validate webhook payload structure

Checks if payload has required fields and correct types

Parameters

Returns

WebhookValidation

Validation result with details

Inherited from

BaseWebhookHandler.validate

verify()

verify(payload, options): boolean

Verify Azure webhook signature

Azure can optionally sign webhooks using HMAC-SHA256. The signature is sent in the X-Azure-Signature header.

Note: Signature verification is optional in Azure and must be configured when creating the webhook.

Parameters

Returns

boolean

true if signature is valid or no signature provided

Example

const isValid = handler.verify(req.body, {
  signature: req.headers['x-azure-signature'],
  secret: process.env.AZURE_WEBHOOK_SECRET,
  rawBody: req.rawBody
});

Overrides

BaseWebhookHandler.verify

Properties

provider

readonly provider: TranscriptionProvider = "azure-stt"

Provider name

Overrides

BaseWebhookHandler.provider

DeepgramWebhookHandler

Deepgram webhook handler

Handles webhook callbacks from Deepgram API. Deepgram sends the full transcription response to the callback URL when transcription is complete.

Note: Deepgram does not provide webhook signature verification. For security, use HTTPS and validate the request source.

Examples

import { DeepgramWebhookHandler } from '@meeting-baas/sdk';

const handler = new DeepgramWebhookHandler();

// Validate webhook
const validation = handler.validate(req.body);
if (!validation.valid) {
  return res.status(400).json({ error: validation.error });
}

// Parse webhook
const event = handler.parse(req.body);
console.log('Event type:', event.eventType);
console.log('Transcript:', event.data?.text);
console.log('Speakers:', event.data?.speakers);

const event = handler.parse(req.body);

if (event.eventType === 'transcription.completed') {
  console.log('Request ID:', event.data?.id);
  console.log('Transcript:', event.data?.text);
  console.log('Duration:', event.data?.duration);
  console.log('Confidence:', event.data?.confidence);

  // Access word-level timestamps
  event.data?.words?.forEach(word => {
    console.log(`${word.text}: ${word.start}s - ${word.end}s`);
  });

  // Access speaker diarization
  event.data?.speakers?.forEach(speaker => {
    console.log(`Speaker ${speaker.speaker}: ${speaker.text}`);
  });
}

Extends

• BaseWebhookHandler

Constructors

Constructor

new DeepgramWebhookHandler(): DeepgramWebhookHandler

Returns

DeepgramWebhookHandler

Inherited from

BaseWebhookHandler.constructor

Methods

createErrorEvent()

protected createErrorEvent(payload, errorMessage): UnifiedWebhookEvent

Helper method to create error response

Parameters

Returns

UnifiedWebhookEvent

Inherited from

BaseWebhookHandler.createErrorEvent

matches()

matches(payload, _options?): boolean

Check if payload matches Deepgram webhook format

Parameters

Returns

boolean

Overrides

BaseWebhookHandler.matches

parse()

parse(payload, _options?): UnifiedWebhookEvent

Parse Deepgram webhook payload to unified format

Parameters

Returns

UnifiedWebhookEvent

Overrides

BaseWebhookHandler.parse

validate()

validate(payload, options?): WebhookValidation

Validate webhook payload structure

Checks if payload has required fields and correct types

Parameters

Returns

WebhookValidation

Validation result with details

Inherited from

BaseWebhookHandler.validate

verify()

verify(): boolean

Verify Deepgram webhook signature

Note: Deepgram does not currently support webhook signature verification. For security, use HTTPS and validate the request source (IP allowlist, etc.).

Returns

boolean

Always returns true (no verification available)

Overrides

BaseWebhookHandler.verify

Properties

provider

readonly provider: TranscriptionProvider = "deepgram"

Provider name

Overrides

BaseWebhookHandler.provider

GladiaWebhookHandler

Gladia webhook handler

Handles webhook callbacks from Gladia API:

• transcription.success - Job completed successfully (includes full transcript)
• transcription.error - Job failed with error

Example

import { GladiaWebhookHandler } from '@meeting-baas/sdk';

const handler = new GladiaWebhookHandler();

// Validate webhook
const validation = handler.validate(req.body);
if (!validation.valid) {
  return res.status(400).json({ error: validation.error });
}

// Parse webhook
const event = handler.parse(req.body);
console.log('Event type:', event.eventType);
console.log('Job ID:', event.data?.id);

if (event.eventType === 'transcription.completed') {
  console.log('Transcript:', event.data?.text);
  console.log('Utterances:', event.data?.utterances);
}

Extends

• BaseWebhookHandler

Constructors

Constructor

new GladiaWebhookHandler(): GladiaWebhookHandler

Returns

GladiaWebhookHandler

Inherited from

BaseWebhookHandler.constructor

Methods

createErrorEvent()

protected createErrorEvent(payload, errorMessage): UnifiedWebhookEvent

Helper method to create error response

Parameters

Returns

UnifiedWebhookEvent

Inherited from

BaseWebhookHandler.createErrorEvent

mapUtterance()

private mapUtterance(utterance): Utterance

Convert Gladia UtteranceDTO to unified Utterance type

Parameters

Returns

Utterance

mapWord()

private mapWord(w): Word

Convert Gladia WordDTO to unified Word type

Parameters

Returns

Word

matches()

matches(payload, _options?): boolean

Check if payload matches Gladia webhook format

Gladia callbacks have the structure:

• { id, event: "transcription.success", payload: TranscriptionResultDTO, custom_metadata? }
• { id, event: "transcription.error", error: ErrorDTO, custom_metadata? }

Parameters

Returns

boolean

Overrides

BaseWebhookHandler.matches

parse()

parse(payload, _options?): UnifiedWebhookEvent

Parse Gladia webhook payload to unified format

Parameters

Returns

UnifiedWebhookEvent

Overrides

BaseWebhookHandler.parse

validate()

validate(payload, options?): WebhookValidation

Validate webhook payload structure

Checks if payload has required fields and correct types

Parameters

Returns

WebhookValidation

Validation result with details

Inherited from

BaseWebhookHandler.validate

verify()

verify(): boolean

Verify Gladia webhook signature

Note: As of the current API version, Gladia does not provide webhook signature verification. This method is a placeholder for future implementation.

Returns

boolean

Always returns true (no verification available)

Overrides

BaseWebhookHandler.verify

Properties

provider

readonly provider: TranscriptionProvider = "gladia"

Provider name

Overrides

BaseWebhookHandler.provider

SpeechmaticsWebhookHandler

Speechmatics webhook handler

Handles webhook callbacks from Speechmatics API. Speechmatics sends job completion notifications via POST with:

• Query parameters: id (job ID) and status (success/error/fetch_error/trim_error)
• User agent: "Speechmatics-API/2.0"
• Body: transcript JSON or multipart data depending on configuration

See

https://docs.speechmatics.com/features-other/notifications

Example

import { SpeechmaticsWebhookHandler } from '@meeting-baas/sdk';

const handler = new SpeechmaticsWebhookHandler();

// Validate webhook
const validation = handler.validate(req.body, {
  queryParams: req.query,  // Include query params for status check
  userAgent: req.headers['user-agent']
});

if (!validation.valid) {
  return res.status(400).json({ error: validation.error });
}

// Parse webhook
const event = handler.parse(req.body, {
  queryParams: req.query
});

if (event.eventType === 'transcription.completed') {
  console.log('Transcript:', event.data?.text);
}

Extends

• BaseWebhookHandler

Constructors

Constructor

new SpeechmaticsWebhookHandler(): SpeechmaticsWebhookHandler

Returns

SpeechmaticsWebhookHandler

Inherited from

BaseWebhookHandler.constructor

Methods

createErrorEvent()

protected createErrorEvent(payload, errorMessage): UnifiedWebhookEvent

Helper method to create error response

Parameters

Returns

UnifiedWebhookEvent

Inherited from

BaseWebhookHandler.createErrorEvent

matches()

matches(payload, options?): boolean

Check if payload matches Speechmatics webhook format

Parameters

Returns

boolean

Overrides

BaseWebhookHandler.matches

parse()

parse(payload, options?): UnifiedWebhookEvent

Parse webhook payload into unified event format

Parameters

Returns

UnifiedWebhookEvent

Overrides

BaseWebhookHandler.parse

validate()

validate(payload, options?): object

Validate webhook request

Parameters

Returns

object

valid

valid: boolean

error?

optional error: string

Overrides

BaseWebhookHandler.validate

verify()?

optional verify(payload, options): boolean

Verify webhook signature (if provider supports it)

Optional method - implement if provider supports webhook signature verification

Parameters

Returns

boolean

true if signature is valid

Example

verify(payload, options) {
  if (!options.signature || !options.secret) return false

  const computed = crypto
    .createHmac('sha256', options.secret)
    .update(JSON.stringify(payload))
    .digest('hex')

  return computed === options.signature
}

Inherited from

BaseWebhookHandler.verify

Properties

provider

readonly provider: TranscriptionProvider = "speechmatics"

Provider name

Overrides

BaseWebhookHandler.provider

Functions

createAssemblyAIWebhookHandler()

createAssemblyAIWebhookHandler(): AssemblyAIWebhookHandler

Factory function to create an AssemblyAI webhook handler

Returns

AssemblyAIWebhookHandler

createAzureWebhookHandler()

createAzureWebhookHandler(): AzureWebhookHandler

Factory function to create an Azure webhook handler

Returns

AzureWebhookHandler

createDeepgramWebhookHandler()

createDeepgramWebhookHandler(): DeepgramWebhookHandler

Factory function to create a Deepgram webhook handler

Returns

DeepgramWebhookHandler

createGladiaWebhookHandler()

createGladiaWebhookHandler(): GladiaWebhookHandler

Factory function to create a Gladia webhook handler

Returns

GladiaWebhookHandler

References

BaseWebhookHandler

Re-exports BaseWebhookHandler

createWebhookRouter

Re-exports createWebhookRouter

GladiaWebhookPayload

Re-exports GladiaWebhookPayload

ProviderWebhookPayloadMap

Re-exports ProviderWebhookPayloadMap

UnifiedWebhookEvent

Re-exports UnifiedWebhookEvent

WebhookEventType

Re-exports WebhookEventType

WebhookRouter

Re-exports WebhookRouter

WebhookRouterOptions

Re-exports WebhookRouterOptions

WebhookRouterResult

Re-exports WebhookRouterResult

WebhookValidation

Re-exports WebhookValidation

WebhookVerificationOptions

Re-exports WebhookVerificationOptions