Webhooks API

create(options: CreateWebhookEndpointOptions): Promise<CreatedWebhookEndpoint>

import { Eyeball } from "@eyeball/sdk";

const eyeball = new Eyeball({
  apiKey: process.env.EYEBALL_API_KEY!,
  baseUrl: process.env.EYEBALL_EXECUTOR_URL!,
});

const endpoint = await eyeball.webhooks.create({
  url: "https://agent.example.com/eyeball",
  events: ["execution.completed", "trigger.slack.message_received"],
});
console.log(endpoint.secret);

delete(endpointId: string): Promise<void>

deliveries(endpointId: string, options?: ListWebhookDeliveriesOptions): Promise<WebhookDeliveryPage>

get(endpointId: string): Promise<WebhookEndpoint>

list(options?: ListWebhookEndpointsOptions): Promise<WebhookEndpointPage>

rotateSecret(endpointId: string): Promise<RotatedWebhookSecret>

update(endpointId: string, options: UpdateWebhookEndpointOptions): Promise<WebhookEndpoint>

createWebhookSignature(options: CreateWebhookSignatureOptions): string

verifyWebhookSignature(options: VerifyWebhookSignatureOptions): boolean

export interface CreateWebhookEndpointOptions {
  url: string;
  events: readonly WebhookSubscriptionEventType[];
  active?: boolean;
}

export interface UpdateWebhookEndpointOptions {
  url?: string;
  events?: readonly WebhookSubscriptionEventType[];
  active?: boolean;
}

export interface ListWebhookEndpointsOptions {
  cursor?: string;
  limit?: number;
}

export interface ListWebhookDeliveriesOptions {
  cursor?: string;
  limit?: number;
}

export interface CreatedWebhookEndpoint extends WebhookEndpoint {
  /** Returned only by endpoint creation. Store this value immediately. */
  secret: string;
}

export interface RotatedWebhookSecret {
  endpointId: string;
  secretPrefix: string;
  /** Returned only by secret rotation. Store this value immediately. */
  secret: string;
  rotatedAt: string;
}

export interface VerifyWebhookSignatureOptions {
  /** Exact request bytes. Verify before parsing JSON. */
  payload: string | Uint8Array;
  headers: WebhookHeaderSource;
  secret: string;
  /** Defaults to five minutes. */
  toleranceMs?: number;
  /** Test seam; defaults to the current wall-clock time. */
  now?: number | Date;
}

export interface WebhookDelivery {
  deliveryId: string;
  endpointId: string;
  eventId: string;
  eventType: WebhookEventType;
  status: WebhookDeliveryStatus;
  attempts: readonly WebhookDeliveryAttempt[];
  createdAt: string;
  nextRetryAt?: string;
  completedAt?: string;
}

export interface WebhookDeliveryAttempt {
  attempt: number;
  attemptedAt: string;
  completedAt: string;
  statusCode?: number;
  error?: string;
}

export interface WebhookDeliveryPage {
  deliveries: readonly WebhookDelivery[];
  nextCursor?: string;
}

export type WebhookDeliveryStatus =
  | "pending"
  | "delivering"
  | "succeeded"
  | "failed";

export interface WebhookEndpoint {
  endpointId: string;
  url: string;
  secretPrefix: string;
  events: readonly WebhookSubscriptionEventType[];
  active: boolean;
  createdAt: string;
  updatedAt: string;
}

export interface WebhookEndpointPage {
  webhooks: readonly WebhookEndpoint[];
  nextCursor?: string;
}

export interface VoiceObserverFailedWebhookData {
  sessionId: string;
  agentId: string;
  agentRevision: number;
  lastHandledSequence: number;
  attempts: number;
  reason: VoiceObserverFailureReason;
  operation: VoiceObserverFailureOperation;
  error: NormalizedToolError;
}

export interface VoiceObserverFailedWebhookEvent {
  id: string;
  type: "voice.observer.failed";
  createdAt: string;
  projectId: string;
  data: VoiceObserverFailedWebhookData;
}

export type VoiceObserverFailureOperation =
  | "get_events"
  | "get_session"
  | "publish_event"
  | "publish_transcript"
  | "publish_failure";

export type VoiceObserverFailureReason = "retry_exhausted" | "non_retryable";

export type WebhookEvent =
  | ExecutionWebhookEvent
  | VoiceSessionWebhookEvent
  | VoiceTranscriptWebhookEvent
  | VoiceObserverFailedWebhookEvent
  | TriggerWebhookEvent;

export type WebhookEventType =
  | TerminalEventType
  | "voice.session.event"
  | "voice.transcript.ready"
  | "voice.observer.failed"
  | TriggerWebhookEventType;

export type WebhookSubscriptionEventType =
  | (typeof WEBHOOK_SUBSCRIPTION_EVENT_TYPES)[number]
  | TriggerWebhookEventType;