Cloud Flow Types

Cloud Flow provides server-side logic for an ioLoop Project. When creating a Cloud Flow module in the Project Editor, choose a Background Task or a Web Hook.

The type determines how the module is made available to the rest of the Project. Choose it based on how the backend functionality needs to be used, not simply on whether the work takes a short or long time.

• Use a Background Task for backend functionality that is not exposed as an HTTP request endpoint, including shared backend helpers.
• Use a Web Hook when a Page, custom frontend, external service, or other request-based caller needs to send an HTTP request and receive a response.

AI Agent function and table-related flows also run on the backend, but they belong to the AI Agent configuration model rather than being treated as ordinary Background Tasks or Web Hooks.

Choosing the Right Type

Requirement	Recommended Type	Why
A Page or Form needs a result from trusted backend processing	Web Hook	Provides a request/response interface for frontend callers.
A custom frontend calls server-side functionality using supported ioLoop APIs	Web Hook	Makes the server operation available through a request-based interface.
An external service sends events or notifications to the Project	Web Hook	Receives and processes HTTP requests.
Several backend modules need the same validation or formatting helper	Background Task	Can provide shared runtime functions through Flow Share without exposing an HTTP endpoint.
The Project needs backend maintenance or data-processing logic that is not an HTTP endpoint	Background Task	The module's own logic determines what work runs and when.
The Project needs periodic backend processing controlled by a timer	Background Task	Timer behavior can be implemented inside the module; no separate scheduling configuration is required.
An AI Agent needs a function tool or table-related operation	AI Agent-specific Flow	Uses the agent's own configuration and invocation model.

For example, a registration Page that must validate capacity and report success or failure would commonly call a Web Hook. A reusable helper used by several registration Web Hooks could instead be defined in a Background Task and shared through Flow Share.

Background Tasks have no separate trigger or scheduling configuration. What a Background Task does—including whether it runs recurring work—is determined by the logic inside the module. For example, the module can implement a timer. Creating a Background Task does not automatically create a recurring schedule.

Background Tasks

A Background Task is a Cloud Flow module for server-side processing that is not exposed as a Web Hook URL.

Use Background Tasks for:

• Backend processing that does not require an HTTP request/response endpoint.
• Maintenance or data-preparation logic executed according to the module's own implementation, including timer-driven logic when needed.
• Initialization logic and common functionality needed by other backend modules.
• Shared validation, formatting, lookup, and integration helper functions.
• Shared runtime values made available through Flow Share.

Execution Defined by Background Task Logic

A Background Task has no separate scheduling or trigger settings. Its runtime behavior comes from the logic defined inside the module. Depending on the implementation, it can initialize shared backend values, perform processing, or establish a timer for recurring work.

A timer is part of the Background Task's own logic, not a separate Cloud Flow scheduler configuration. Design the logic to handle errors and repeated execution appropriately. Do not assume that simply creating a Background Task will run a particular operation periodically.

Background Tasks as Shared Modules

A Background Task can act as a shared backend module rather than a standalone piece of scheduled work.

For example, several Web Hooks may need to validate order input in the same way. Instead of maintaining separate copies of the logic, a shared Background Task can define the helper and expose it through Flow Share.

Background Task: SharedOrderHelpers
  Defines reusable validation helper
  Publishes helper through Flow Share

Web Hook: CreateOrder
  Reads helper from Flow Share
  Validates the incoming request
  Performs the permitted operation
  Returns a response

Web Hook: UpdateOrder
  Reads the same helper from Flow Share
  Validates the incoming request
  Performs the permitted operation
  Returns a response

This diagram illustrates module responsibilities, not specific Cloud Flow blocks or API syntax.

Shared values and helpers must be available before dependent modules attempt to use them. Flow Share is runtime-only sharing, not durable storage. Store persistent records, files, and long-lived application data in the appropriate Database or file storage capability.

Background Tasks are already secured by ioLoop and do not require the Web Hook Access (Security) configuration. This does not remove the need to validate inputs or enforce business rules in backend operations that use shared helpers.

For implementation guidance and examples, see Background Tasks and Flow Share.

Web Hooks

A Web Hook is a Cloud Flow module that receives an HTTP request and produces a response.

Use Web Hooks when:

• Page Flow needs to invoke trusted server-side processing.
• A custom frontend needs a request-based server operation.
• A Form submission must enforce protected business rules.
• An external service needs to send an event to the Project.
• The caller needs a result, such as confirmation, validation feedback, or permitted data.

A Web Hook can read or change Project data, invoke Connections, process files, and use other supported Server API functionality as part of its workflow.

Example: Registering for an Event

A registration workflow might work as follows:

1. A visitor completes the registration Form, or an equivalent custom frontend interface.
2. Page Flow or custom JavaScript sends the required request data to a Cloud Flow Web Hook.
3. The Web Hook validates the request and the applicable authorization or business rules.
4. Cloud Flow checks registration capacity and performs the permitted Database operation.
5. The Web Hook returns an appropriate success or failure response.
6. The frontend updates the interface based on the result.

The Web Hook supplies the trusted processing boundary. It does not make client-provided values trustworthy merely because they arrived through HTTP.

Web Hook Configuration and Access

Web Hooks have request-facing configuration, including their name, HTTP method, response behavior, and Access (Security) settings. The appropriate configuration depends on whether the caller is a Page, authenticated Project User, external service, or another permitted system.

A Web Hook can be intentionally public, but a public endpoint must still validate its requests and limit what it returns. Do not treat an unadvertised URL as an authentication mechanism.

For configuration details, see Web Hooks and Access Security.

AI Agent-Related Flows

AI Agents can use backend flow logic for function tools, table-related behavior, and other agent-specific processing.

These flows are part of the AI Agent model. Their configuration, inputs, permissions, and invocation context should be understood through the relevant AI Agent documentation rather than by assuming they behave like a normal Web Hook or Background Task.

Where agent modules consume helpers exposed by Background Tasks, the same Flow Share and load-order considerations apply.

For details, see AI Agents and Function Knowledge Sources.

Module Loading and Flow Share

Cloud Flow module loading is related to, but different from, deciding how a workflow is invoked.

ioLoop loads the backend module types in this order:

1. Background Tasks
2. Web Hooks
3. AI Agent modules

Within each type, modules with lower load-order values load before modules with higher values.

This order matters when a module provides a Flow Share helper that another module expects to use. For example, a shared Background Task should load before a dependent Background Task or Web Hook.

Load order does not create an HTTP endpoint or configure a timer or schedule. It controls how modules are loaded in the Cloud Flow runtime. Any recurring execution is defined by the logic inside the Background Task itself.

Use Load Order - and Load Order + in the Cloud Flow module list to arrange dependencies where needed. For implementation details, see Managing Cloud Flow and Flow Share.

Type and Security

The selected type determines the entry point, but protected business behavior must still be enforced by trusted logic.

Type	Primary Security Consideration
Background Task	Not exposed as a Web Hook; already secured by ioLoop. Validate data and enforce the intended rules wherever its logic is used.
Web Hook	Configure invocation access, validate incoming requests, authenticate external callers where required, and authorize sensitive operations.
AI Agent-related Flow	Validate permissions for the agent tool and the user or execution context associated with the operation.

For all backend types:

• Treat browser-supplied and external data as untrusted input.
• Verify record-specific permissions and important business rules on the server.
• Use configured Connections for protected external-service credentials.
• Return only the information the caller is allowed to receive.
• Test both permitted and denied operations.

A permitted frontend Database operation may use the ioLoop Client API directly. Use Cloud Flow when the workflow needs trusted processing or functionality available only through the broader Server API.

Testing the Selected Type

Test each module through the way it is actually intended to be used.

Type	What to Test
Background Task	Its implemented behavior, including initialization, internal timer logic (if used), repeated execution, errors, and helpers or values expected by dependent modules.
Web Hook	Valid and invalid requests, access restrictions, success and failure responses, and the real Page or external caller.
AI Agent-related Flow	The configured agent invocation, inputs, tool permissions, and allowed or denied outcomes.

For shared modules, also verify that Flow Share dependencies are ready before the consumer needs them.

When testing Database operations through the Project development environment, verify the intended data context. Built-in Database operations during Preview use the development database; external services and Connections may still have independent test or live modes and side effects.

For test-runtime and logging guidance, see Testing and Logs.

Good Practices

• Choose by invocation model. Use a Web Hook for HTTP request/response behavior and a Background Task for non-endpoint backend functionality.
• Define execution in the module. Background Tasks have no separate scheduling settings; implement any timers or recurring work inside the Background Task logic.
• Share helpers intentionally. Use Background Tasks and Flow Share for common runtime functionality when reuse is valuable.
• Keep dependencies clear. Arrange shared modules before their consumers.
• Configure Web Hook access deliberately. Public endpoints should be a conscious choice.
• Keep authorization separate from presentation. Never rely on hidden frontend controls for backend security.
• Test the actual entry point. A module should be verified through its intended caller or execution path.

Common Mistakes

Avoid these patterns:

• Choosing Background Task solely because a workflow will take a long time, even though a Page needs a request/response interface.
• Assuming Background Task creation automatically establishes a recurring schedule, or looking for a separate Background Task scheduling configuration.
• Creating a public Web Hook when no public endpoint is needed.
• Assuming a Web Hook is secure because its URL is difficult to guess.
• Using Flow Share to store data that must survive a runtime restart.
• Forgetting load-order dependencies for shared helpers.
• Treating AI Agent-specific flows as interchangeable with ordinary Web Hooks.
• Assuming Cloud Flow access configuration alone enforces every record-specific business rule.

Cloud Flow types are most useful when their invocation model matches the application's need. Keep the choice simple: Background Task for non-endpoint backend modules, Web Hook for HTTP request/response workflows, and AI Agent-specific flows for agent behavior.

Related Topics

• Cloud Flow
• Managing Cloud Flow
• Background Tasks
• Web Hooks
• Flow Share
• Access Security
• Testing and Logs
• Calling Cloud Flow from Pages
• AI Agents
• Cloud Flow Blocks
• Server API