Voice Router SDK - Webhook Normalization / types

types

Interfaces

UnifiedWebhookEvent

Unified webhook event with provider-specific type safety

When a specific provider is known at compile time, the raw field will be typed with that provider's actual webhook payload type.

Example

const event: UnifiedWebhookEvent<'gladia'> = handler.parse(payload);
// event.raw is typed as GladiaWebhookPayload
if ('payload' in event.raw) {
  const transcription = event.raw.payload; // TranscriptionResultDTO
}

Type Parameters

Properties

eventType

eventType: WebhookEventType

Type of webhook event

provider

provider: P

Provider that sent this webhook

raw

raw: P extends keyof ProviderWebhookPayloadMap ? ProviderWebhookPayloadMap[P<P>] : unknown

Original webhook payload (fully typed per provider)

Type-safe based on the provider:

• gladia: GladiaWebhookPayload
• assemblyai: AssemblyAIWebhookPayload
• deepgram: DeepgramWebhookPayload

success

success: boolean

Whether the operation was successful

timestamp

timestamp: string

Event timestamp

data?

optional data: object

Transcription data (if available)

id

id: string

Transcription job ID

status

status: TranscriptionStatus

Current status

completedAt?

optional completedAt: string

Completion timestamp

confidence?

optional confidence: number

Overall confidence score

createdAt?

optional createdAt: string

Creation timestamp

duration?

optional duration: number

Audio duration in seconds

error?

optional error: string

Error message (only for failed events)

language?

optional language: string

Detected or specified language

metadata?

optional metadata: Record<string, unknown>

Additional provider-specific metadata

speakers?

optional speakers: Speaker[]

Speaker diarization results

summary?

optional summary: string

Summary of content

text?

optional text: string

Full transcribed text (only for completed events)

utterances?

optional utterances: Utterance[]

Utterances (speaker turns)

words?

optional words: Word[]

Word-level transcription

WebhookValidation

Webhook validation result

Properties

valid

valid: boolean

Whether the webhook is valid

details?

optional details: Record<string, unknown>

Additional validation details

error?

optional error: string

Error message (if invalid)

provider?

optional provider: TranscriptionProvider

Detected provider (if valid)

WebhookVerificationOptions

Webhook signature verification options

Properties

headers?

optional headers: Record<string, string>

Custom headers from the webhook request

rawBody?

optional rawBody: string | Buffer<ArrayBufferLike>

Raw request body (for signature verification)

secret?

optional secret: string

Webhook secret key

signature?

optional signature: string

Webhook signature from headers

timestamp?

optional timestamp: string

Timestamp from headers (for replay attack prevention)

References

AssemblyAIWebhookPayload

Re-exports AssemblyAIWebhookPayload

DeepgramWebhookPayload

Re-exports DeepgramWebhookPayload

GladiaWebhookErrorPayload

Re-exports GladiaWebhookErrorPayload

GladiaWebhookSuccessPayload

Re-exports GladiaWebhookSuccessPayload

Type Aliases

GladiaWebhookPayload

GladiaWebhookPayload = GladiaWebhookSuccessPayload | GladiaWebhookErrorPayload

Union of all Gladia webhook payloads

ProviderWebhookPayloadMap

ProviderWebhookPayloadMap = object

Map of provider names to their webhook payload types

Properties

assemblyai

assemblyai: AssemblyAIWebhookPayload

azure-stt

azure-stt: unknown

deepgram

deepgram: DeepgramWebhookPayload

gladia

gladia: GladiaWebhookPayload

openai-whisper

openai-whisper: never

speechmatics

speechmatics: unknown

WebhookEventType

WebhookEventType = "transcription.created" | "transcription.processing" | "transcription.completed" | "transcription.failed" | "live.session_started" | "live.session_ended" | "live.transcript"

Unified webhook event types