# Custom Module

The Custom Module pauses a Workflow and hands control to your application, which runs custom logic and returns a result that determines how the Workflow continues. Use it to integrate Workflows with external systems, partner APIs, or proprietary business rules while keeping the end user in a single, seamless journey.

## Integrations

:white_check_mark: Web | :white_check_mark: iOS | :white_check_mark: Android

{/* TODO: Confirm with PM — Notion lists Web SDK support as "TBC" with iOS v5.39.0 and Android v5.42.0 as the minimum versions. Confirm Web SDK availability and minimum versions for all three platforms before publishing. */}

<Callout icon="⚠️" theme="warn">
  ### SDK Required

  The Custom Module requires an SDK integration to function. Dashboard configuration alone is not enough. The callback that resumes the Workflow is implemented in your SDK code.
</Callout>

## How It Works

The Workflow configuration in Dashboard defines which Custom Module runs and where it sits in the Workflow. The SDK callback (`onCustomModuleStarted`) defines what happens when the module runs. Both pieces are required.

### Responsibilities

**Incode** runs the Workflow and manages the pause and resume around the Custom Module.

**Your integration** implements the `onCustomModuleStarted` callback in the SDK, runs whatever logic the use case requires (such as a partner API call, a risk-engine evaluation, a custom UI screen, or a business rule check), and returns a result.

### Execution Flow

1. The Workflow runs until it reaches the Custom Module, then pauses.
2. The SDK invokes your `onCustomModuleStarted` callback.
3. Your callback runs its logic and returns one of three [results](#results).
4. The Workflow resumes and branches based on the returned result.

### Results

Your callback must return exactly one of the following:

| Result      | Path                |
| ----------- | ------------------- |
| `onSuccess` | Approved/pass       |
| `onFail`    | Rejected/fail       |
| `onUnknown` | No decision/step-up |

**Important:** If your callback does not return a result, the Workflow stays paused indefinitely. This is the most common integration issue. Make sure every code path in your callback, including error handlers, returns a result.

### When to Use the Custom Module

The Custom Module is the right choice when:

- A decision needs to happen outside of Incode
- Your business logic shouldn't live in Incode's platform
- The Workflow's next step depends on an external system, partner API, or proprietary rule
- You need to insert a custom screen or step-up prompt mid-Workflow

The Custom Module is **not** intended for:

- Long-running or delayed decisions; the Workflow stays paused while the callback runs, so the operation should complete in a reasonable time
- Logic that Incode already provides as a standard module
- Workflows where no customer-side integration is available to handle the callback

## Use Custom Module

The Custom Module requires **both** Dashboard configuration and an SDK integration. See the following pages:

- [Custom Module (Dashboard)](https://developer.incode.com/docs/custom-module-dashboard)
- [Custom Module (iOS)](https://developer.incode.com/docs/custom-module-ios)
- [Custom Module (Android)](https://developer.incode.com/docs/custom-module-android)
- [Custom Module (Web SDK)](https://developer.incode.com/docs/custom-module-web-sdk)

<br />