Events API

The Embedding SDK emits events when users interact with the embedded FlowStack components. Use these events to synchronize state between your app and FlowStack.

Event Callbacks

React

<FlowStackEmbed
  token={token}
  view="builder"
  onFlowCreated={(flow) => {
    console.log('New flow created:', flow.id, flow.name);
    // Save flow reference to your database
  }}
  onFlowUpdated={(flow) => {
    console.log('Flow updated:', flow.id);
  }}
  onFlowDeleted={(flowId) => {
    console.log('Flow deleted:', flowId);
    // Remove flow reference from your database
  }}
  onFlowRun={(run) => {
    console.log('Run completed:', run.id, run.status);
    // Update run count in your UI
  }}
  onConnectionCreated={(connection) => {
    console.log('New connection:', connection.app);
  }}
  onError={(error) => {
    console.error('FlowStack error:', error.message);
    // Show error notification in your UI
  }}
  onReady={() => {
    console.log('FlowStack embed loaded');
  }}
/>

Vanilla JavaScript

FlowStack.embed({
  container: '#flowstack-container',
  token: token,
  view: 'builder',
  on: {
    flowCreated: (flow) => console.log('Created:', flow),
    flowUpdated: (flow) => console.log('Updated:', flow),
    flowDeleted: (flowId) => console.log('Deleted:', flowId),
    flowRun: (run) => console.log('Run:', run),
    connectionCreated: (conn) => console.log('Connected:', conn),
    error: (err) => console.error('Error:', err),
    ready: () => console.log('Ready'),
  },
});

Event Reference

onFlowCreated

Fired when a user creates a new flow.

interface FlowCreatedEvent {
  id: string;
  name: string;
  engine: 'activepieces' | 'n8n';
  status: 'INACTIVE';
  created: string; // ISO 8601
}

onFlowUpdated

Fired when a user saves changes to a flow.

interface FlowUpdatedEvent {
  id: string;
  name: string;
  status: 'ACTIVE' | 'INACTIVE';
  updated: string;
}

onFlowDeleted

Fired when a user deletes a flow.

type FlowDeletedEvent = string; // flow ID

onFlowRun

Fired when a flow execution completes (success or failure).

interface FlowRunEvent {
  id: string;
  flowId: string;
  status: 'SUCCEEDED' | 'FAILED';
  duration: number; // milliseconds
  triggerType: 'MANUAL' | 'SCHEDULE' | 'WEBHOOK' | 'APP_EVENT';
  startTime: string;
  finishTime: string;
}

onConnectionCreated

Fired when a user connects a new app.

interface ConnectionCreatedEvent {
  id: string;
  name: string;
  app: string;
  type: 'OAUTH2' | 'API_KEY' | 'BASIC_AUTH';
}

onError

Fired when an error occurs in the embedded component.

interface ErrorEvent {
  code: string;
  message: string;
  details?: Record<string, unknown>;
}

onReady

Fired when the embedded component has fully loaded and is ready for interaction. No payload.

Programmatic Control

Call methods on the embed instance to control it programmatically:

const embed = FlowStack.embed({ container: '#container', token });

// Navigate to a specific view
embed.navigate('connections');

// Open a specific flow for editing
embed.openFlow('flow_abc123');

// Refresh the current view
embed.refresh();

// Destroy the embed instance
embed.destroy();