Webhook Types

Mixed SDK/API Types: Webhook class and WebhookEvent conform to the Webhooks API. WebhookListener and related types are SDK-specific helpers for handling inbound webhook requests with signature verification.

See Webhooks for usage.

WebhookEvent

enum WebhookEvent {
  COMPLETED = 'completed',
  FAILED    = 'failed',
  CANCELED  = 'canceled',
  STARTED   = 'started',
}

Webhook Class

class Webhook {
  readonly url: string;
  readonly events: readonly WebhookEvent[];
  
  constructor(url: string, events: WebhookEvent[]);
  toJSON(): WebhookPayload;
}

Member	Type	Description
`url`	`string`	Callback URL.
`events`	`readonly WebhookEvent[]`	Events to subscribe to.
`.toJSON()`	`WebhookPayload`	Serialize for API calls.

WebhookListener Class

class WebhookListener {
  on(route: WebhookRoute, handler: (prediction: PredictionResponse) => void | Promise<void>): this;
  off(route: WebhookRoute, handler: Function): this;
  handle(rawBody: string, headers: Record<string, string>): Promise<PredictionResponse>;
  handleRequest(request: Request): Promise<Response>;
  dispatch(prediction: PredictionResponse): Promise<void>;
}

See Inbound Webhooks.

Method	Description
`.on(route, handler)`	Register a handler. Alias: `listen()`.
`.off(route, handler)`	Remove a handler.
`.handle(rawBody, headers)`	Verify + parse + dispatch.
`.handleRequest(request)`	Web `Request` → `Response`.
`.dispatch(prediction)`	Skip verification, run handlers directly.

WebhookRoute

type WebhookRoute =
  | WebhookEvent
  | `prediction.${PredictionStatus}`
  | 'prediction.*'
  | '*'

WebhookVerifyOptions

interface WebhookVerifyOptions {
  mode?: 'general' | 'enterprise';
  secret?: string;
  apiKey?: string;
}

Field	Type	Description
`mode`	`'general' \| 'enterprise'`	`'general'` uses `sk-…` key; `'enterprise'` uses dashboard secret.
`secret`	`string`	Enterprise webhook secret.
`apiKey`	`string`	Platform API key (for `'general'` mode).

WebhookListenerOptions

interface WebhookListenerOptions {
  mode?: 'general' | 'enterprise';
  verifySignature?: boolean;
  secret?: string;
  apiKey?: string;
}

Field	Type	Default	Description
`mode`	`'general' \| 'enterprise'`	`'general'`	Verification mode.
`verifySignature`	`boolean`	`true`	Enable HMAC-SHA256 verification.
`secret`	`string`	—	Enterprise secret.
`apiKey`	`string`	—	Platform API key.

SDK Webhooks — Complete webhooks implementation guide
Webhooks API — API webhook concepts and event types
SDK Errors — Error handling including WEBHOOK_SIGNATURE_INVALID

How is this guide?