Voice Router SDK - Webhook Normalization / base-webhook

base-webhook

Classes

abstract BaseWebhookHandler

Abstract base class for webhook handlers

Each provider implements this to parse and normalize their webhook payloads

Extended by

• GladiaWebhookHandler
• AssemblyAIWebhookHandler
• DeepgramWebhookHandler
• AzureWebhookHandler
• SpeechmaticsWebhookHandler

Constructors

Constructor

new BaseWebhookHandler(): BaseWebhookHandler

Returns

BaseWebhookHandler

Methods

createErrorEvent()

protected createErrorEvent(payload, errorMessage): UnifiedWebhookEvent

Helper method to create error response

Parameters

Returns

UnifiedWebhookEvent

matches()

abstract matches(payload, options?): boolean

Check if this payload matches this provider's webhook format

Used for auto-detection of webhook provider

Parameters

Returns

boolean

true if this handler can process the payload

Example

matches(payload, options) {
  return typeof payload === 'object' &&
         'event' in payload &&
         'payload' in payload
}

parse()

abstract parse(payload, options?): UnifiedWebhookEvent

Parse and normalize webhook payload

Converts provider-specific webhook format to UnifiedWebhookEvent

Parameters

Returns

UnifiedWebhookEvent

Normalized webhook event

Throws

Error if payload cannot be parsed

Example

parse(payload, options) {
  const typed = payload as ProviderWebhookPayload
  return {
    success: true,
    provider: this.provider,
    eventType: 'transcription.completed',
    data: { id: typed.job_id, ... },
    timestamp: new Date().toISOString(),
    raw: payload
  }
}

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

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
}

Properties

provider

abstract readonly provider: TranscriptionProvider

Provider name