Voice Router SDK - Webhook Normalization / webhook-router

webhook-router

Classes

WebhookRouter

Webhook router with automatic provider detection

Automatically detects the webhook provider from the payload structure and routes to the appropriate handler for parsing and normalization.

Examples

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

const router = new WebhookRouter();

// Auto-detect provider and parse webhook
const result = router.route(req.body);

if (result.success) {
  console.log('Provider:', result.provider);
  console.log('Event type:', result.event?.eventType);
  console.log('Transcript ID:', result.event?.data?.id);
} else {
  console.error('Error:', result.error);
}

const router = new WebhookRouter();

const result = router.route(req.body, {
  verification: {
    signature: req.headers['x-signature'],
    secret: process.env.WEBHOOK_SECRET,
    rawBody: req.rawBody
  }
});

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

const router = new WebhookRouter();

// Skip auto-detection, use specific provider
const result = router.route(req.body, {
  provider: 'gladia'
});

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 });
  }

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

  // Process webhook event
  console.log('Received webhook from:', result.provider);
  console.log('Event:', result.event);

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

Constructors

Constructor

new WebhookRouter(): WebhookRouter

Returns

WebhookRouter

Methods

detectProvider()

detectProvider(payload, options?): TranscriptionProvider | undefined

Detect provider from webhook payload structure

Parameters

Returns

TranscriptionProvider | undefined

Detected provider or undefined

getHandler()

getHandler(provider): BaseWebhookHandler | undefined

Get handler for a specific provider

Parameters

Returns

BaseWebhookHandler | undefined

Handler instance or undefined

getProviders()

getProviders(): TranscriptionProvider[]

Get all registered providers

Returns

TranscriptionProvider[]

Array of provider names

route()

route(payload, options?): WebhookRouterResult

Route webhook payload to the correct handler

Parameters

Returns

WebhookRouterResult

Routing result with parsed event

routeToProvider()

private routeToProvider(payload, provider, options?): WebhookRouterResult

Route to a specific provider handler

Parameters

Returns

WebhookRouterResult

validate()

validate(payload, options?): WebhookValidation

Validate webhook payload

Parameters

Returns

WebhookValidation

Validation result

verify()

verify(payload, provider, options): boolean

Verify webhook signature

Parameters

Returns

boolean

true if signature is valid

Properties

handlers

private handlers: Map<TranscriptionProvider, BaseWebhookHandler>

Functions

createWebhookRouter()

createWebhookRouter(): WebhookRouter

Factory function to create a webhook router

Returns

WebhookRouter

Interfaces

WebhookRouterOptions

Webhook router options

Properties

provider?

optional provider: TranscriptionProvider

Specific provider to use (skips auto-detection)

queryParams?

optional queryParams: Record<string, string>

Query parameters from the webhook request (e.g., for Speechmatics: ?id=<job_id>&status=success)

userAgent?

optional userAgent: string

User agent from the webhook request headers (e.g., for Speechmatics: "Speechmatics-API/2.0")

verification?

optional verification: WebhookVerificationOptions

Webhook verification options (signature, secret, etc.)

verifySignature?

optional verifySignature: boolean

Whether to verify webhook signatures

Default

true

WebhookRouterResult

Webhook router result

Properties

success

success: boolean

Whether routing was successful

error?

optional error: string

Error message if routing failed

event?

optional event: UnifiedWebhookEvent<TranscriptionProvider>

Parsed unified webhook event

provider?

optional provider: TranscriptionProvider

Detected or specified provider

verified?

optional verified: boolean

Whether signature verification was performed and passed