flow()

Creates a flow object for use in code-native integrations.

The flow() function defines a single flow within a code-native integration. A flow has a trigger (webhook, schedule, or polling) and a main execution function. Flows are passed as an array to the flows field of integration().

Function signature

export const flow = <
  TInputs extends Inputs,
  TActionInputs extends Inputs,
  TPayload extends TriggerPayload = TriggerPayload,
  TAllowsBranching extends boolean = boolean,
  TResult extends TriggerResult<TAllowsBranching, TPayload> = TriggerResult<TAllowsBranching, TPayload>,
  TTriggerPayload extends TriggerPayload = TriggerPayload,
  T extends Flow<TInputs, TActionInputs, TPayload, TAllowsBranching, TResult, TTriggerPayload>
    = Flow<TInputs, TActionInputs, TPayload, TAllowsBranching, TResult, TTriggerPayload>,
>(
  definition: T,
): T

A Flow is a union of StandardFlow (webhook or scheduled trigger) and PollingFlow (polling trigger). The triggerType field determines which variant applies.

Parameters

definition · Flow · required

An object that defines the flow. All base fields apply to both standard and polling flows.

Hide Base flow fields (all flow types)

name · string · required

The unique display name for this flow.

stableKey · string · required

A unique, unchanging identifier for this flow. Even if the name changes, stableKey preserves the flow’s identity in the platform.

description · string

Human-readable description for this flow.

onExecution · FlowOnExecution · required

The main function executed when this flow is invoked. Receives context and params (which includes the trigger payload via params.onTrigger.results).

isSynchronous · boolean · default: "false"

When true, the flow responds synchronously to the HTTP request that triggered it, returning the execution result in the response body.

isAgentFlow · boolean · default: "false"

When true, this flow is an AI agent flow exposed on the integration’s MCP server.

retryConfig · RetryConfig

Retry configuration for this flow when execution fails.

Show RetryConfig fields

maxAttempts · number · required

Maximum number of retry attempts. Must be between 0 and 10.

delayMinutes · number · required

Delay in minutes between retry attempts. Must be between 0 and 60.

usesExponentialBackoff · boolean · required

When true, uses exponential backoff to calculate the delay between attempts.

uniqueRequestIdField · string

Name of the field in the trigger payload to use as a unique request ID for retry deduplication.

queueConfig · QueueConfig

Queue configuration controlling how concurrent executions are handled. See queue config variants below.

endpointSecurityType · EndpointSecurityType · default: "customer_optional"

Security configuration for this flow’s endpoint URL.

Accepted values:

• "unsecured" — No authentication required.
• "customer_optional" — Customer API key is optional.
• "customer_required" — Customer API key is required.
• "organization" — Uses organization-level API keys.

organizationApiKeys · string[]

List of API keys for the endpoint when endpointSecurityType is "organization".

errorConfig · StepErrorConfig

Error handling configuration for steps within this flow.

Show StepErrorConfig fields

errorHandlerType · StepErrorHandlerType · required

The type of error handler: "fail", "ignore", or "retry".

maxAttempts · number

Maximum number of retry attempts (0–5). Only applies when errorHandlerType is "retry".

delaySeconds · number

Delay in seconds between retry attempts (0–60).

usesExponentialBackoff · boolean · default: "false"

When true, uses exponential backoff between step retry attempts.

ignoreFinalError · boolean · default: "false"

When true, ignores the final error after the last retry attempt.

preprocessFlowConfig · PreprocessFlowConfig

Preprocess flow configuration for when this flow’s result contains flow routing attributes. Only one flow per integration may define this.

Show PreprocessFlowConfig fields

flowNameField · string · required

Name of the field in the returned payload used to route to the next flow.

externalCustomerIdField · string

Name of the field used as the external customer ID.

externalCustomerUserIdField · string

Name of the field used as the external customer user ID.

onInstanceDeploy · TriggerEventFunction

Function executed when an instance of this integration is deployed.

onInstanceDelete · TriggerEventFunction

Function executed when an instance of this integration is deleted.

webhookLifecycleHandlers · object

Optional handlers for webhook lifecycle events.

Show webhookLifecycleHandlers fields

create · TriggerEventFunction · required

Function executed to configure (register) the webhook with the external service.

delete · TriggerEventFunction · required

Function executed to remove (deregister) the webhook from the external service.

schemas · Record<string, FlowDefinitionFlowSchema> & { invoke: FlowDefinitionFlowSchema }

Optional JSON Schema definitions for this flow. Currently used only with AI agent flows. Must include an invoke key.

Show FlowDefinitionFlowSchema fields

title · string

Title for the schema.

$comment · string

Optional comment.

$schema · string

JSON Schema version URI. Defaults to "https://json-schema.org/draft/2020-12/schema".

properties · Record<string, { description: string; type?: string }> · required

Properties in the schema, each with a description and optional type.

required · string[]

List of required property names.

Show Standard flow fields (triggerType: 'standard' or unset)

triggerType · 'standard'

Set to "standard" (or omit) for webhook and scheduled flows.

schedule · (ValueExpression<string> | ConfigVarExpression) & { timezone?: string }

Schedule configuration for automatically-executed flows. Use a cron expression as a value, or reference a schedule config variable with configVar.

onTrigger · TriggerReference | TriggerPerformFunction

The trigger function for this flow. Accepts either a reference to a component trigger or an inline function. If omitted, a default webhook trigger is used.

Show Polling flow fields (triggerType: 'polling')

triggerType · 'polling' · required

Must be "polling" to use a polling trigger. Polling flows run on a schedule and have access to context.polling.* functions for managing state between runs.

schedule · (ValueExpression<string> | ConfigVarExpression) & { timezone?: string } · required

Required for polling flows. Defines the polling frequency as a cron expression.

onTrigger · PollingTriggerPerformFunction · required

Required for polling flows. The trigger function that runs on each poll cycle.

Queue config variants

The queueConfig field accepts one of the following shapes:

ParallelQueueConfig

All requests are processed simultaneously with no limits.

queueConfig: {
  type: "parallel",
}

ThrottledQueueConfig

Limits the maximum number of concurrent executions per instance.

queueConfig: {
  type: "throttled",
  concurrencyLimit: 5,    // 2–15
  dedupeIdField: "requestId", // optional
}

SequentialQueueConfig

Processes one execution at a time, in the order received.

queueConfig: {
  type: "sequential",
  dedupeIdField: "requestId", // optional
}

StandardQueueConfig

Fine-grained queue control without a fixed processing mode.

queueConfig: {
  usesFifoQueue: true,         // FIFO ordering
  dedupeIdField: "requestId",  // optional
  singletonExecutions: false,  // only for scheduled/polling flows
  concurrencyLimit: 4,         // 2–15
}

Return type

flow · T

The same flow definition object passed in, unchanged. The function is used for type-checking and inference.

Examples

Standard webhook flow

import { flow } from "@prismatic-io/spectral";

const syncFlow = flow({
  name: "Sync Records",
  stableKey: "sync-records",
  description: "Processes incoming webhook payloads.",
  isSynchronous: false,
  endpointSecurityType: "customer_optional",
  retryConfig: {
    maxAttempts: 3,
    delayMinutes: 5,
    usesExponentialBackoff: true,
  },
  onExecution: async (context, params) => {
    const payload = params.onTrigger.results;
    context.logger.info("Received payload", { payload });
    return { data: null };
  },
});

Related

• integration() — The parent function that accepts an array of flows.
• configPage() — Define config wizard pages referenced in flows.
• componentManifest() — Register components whose actions are available in context.components.