Execution Engine APIs

Complete API reference for BankLingo's Execution Engine - Process Orchestration, Webhooks, and Recurring Jobs.

Overview

The Execution Engine provides three powerful mechanisms for automating business logic:

Process Engine - Orchestrate complex workflows using BPMN 2.0
Webhooks - Integrate with external systems via HTTP callbacks
Recurring Jobs - Schedule periodic tasks using cron expressions

All APIs use the same command/query execution pattern via the /api/v1/execute endpoint.

Process Engine APIs

Execute and manage BPMN process instances for complex multi-step workflows.

Use Cases:

Loan application workflows with approvals
Account opening processes
Transaction processing pipelines
Approval workflows

Key Commands:

StartProcessInstanceCommand - Start a new process instance
SignalProcessInstanceCommand - Resume waiting user tasks
ReturnCallbackCommand - Resume waiting callbacks
GetProcessInstanceByIdQuery - Get process details
CancelProcessInstanceCommand - Cancel running process

View Complete Process APIs Documentation →

Webhook APIs

Configure HTTP endpoints that receive external callbacks and execute commands, code, or processes.

Use Cases:

Payment gateway callbacks (Paystack, Flutterwave)
NIBSS transaction notifications
Third-party API integrations
External system events

Key Commands:

CreateWebHookConfigCommand - Create webhook endpoint
UpdateWebHookConfigCommand - Update webhook configuration
GetWebHookConfigByIdQuery - Get webhook details
GetWebHookConfigListQuery - List all webhooks
DeleteWebHookConfigCommand - Remove webhook

Execution Types:

Execute Command - Run a single command
Execute Code - Run JavaScript expression
Start Process - Trigger a BPMN process

View Complete Webhook APIs Documentation →

Recurring Job APIs

Schedule periodic execution of commands, code, or processes using cron expressions.

Use Cases:

Daily EOD report generation
Monthly interest posting
Automated reconciliation
Data cleanup jobs
System health checks

Key Commands:

CreateRecurringJobCommand - Create scheduled job
UpdateRecurringJobCommand - Update job configuration
GetRecurringJobByIdQuery - Get job details
GetRecurringJobListQuery - List all jobs
ExecuteRecurringJobCommand - Run job immediately
DeleteRecurringJobCommand - Remove job

Execution Types:

Execute Native Command - Run a single command
Execute Command Chain - Run multiple chained commands
Execute Code - Run JavaScript expression
Start Process - Trigger a BPMN process

View Complete Recurring Job APIs Documentation →

Common Patterns

Execution Endpoint

All commands use the same endpoint:

POST /api/v1/execute
Content-Type: application/json
Authorization: Bearer {token}

Request Format

{
  "cmd": "CommandName",
  "data": {
    // Command-specific parameters
  }
}

Response Format

{
  "isSuccessful": true,
  "message": "Operation completed successfully",
  "data": {
    // Response data
  }
}

Error Response

{
  "isSuccessful": false,
  "message": "Error description",
  "errors": [
    {
      "field": "fieldName",
      "message": "Validation error"
    }
  ]
}

Execution Type Comparison

All three systems support multiple execution types:

Execution Type	Process	Webhook	Recurring Job	Description
Command	❌	✅	✅	Execute single command
Command Chain	❌	❌	✅	Execute multiple commands
Code	❌	✅	✅	Execute JavaScript expression
Process	N/A	✅	✅	Start BPMN process instance

Process Engine is itself the execution mechanism, so it doesn't have "execution types" - it orchestrates the other types.

Integration Example

Complete Payment Flow: Webhook → Process → Callback

Step 1: Create Payment Webhook

{
  "cmd": "CreateWebHookConfigCommand",
  "data": {
    "name": "Paystack Payment Callback",
    "url": "/webhook/paystack/payment",
    "executionType": 3,
    "processDefinitionId": 50
  }
}

Step 2: Paystack Sends Callback

POST /webhook/paystack/payment
Content-Type: application/json

{
  "event": "charge.success",
  "data": {
    "reference": "REF123456",
    "amount": 50000,
    "customer": { "email": "john@example.com" }
  }
}

Step 3: Process Executes

Process (ID=50) starts with webhook data in Context variable:

Posts transaction to account
Sends confirmation email
Returns callback to waiting process

Step 4: Original Process Resumes

If payment was triggered from a process:

{
  "cmd": "ReturnCallbackCommand",
  "data": {
    "correlationKey": "REF123456",
    "result": { "status": "success", "amount": 50000 }
  }
}

Security Best Practices

1. Webhook IP Whitelisting

{
  "allowedIPs": ["52.31.139.75", "52.49.173.169"]
}

2. Execution Code Protection

GetById queries: Return executionCode (for editing)
GetList queries: Exclude executionCode (security)

3. Process Authorization

Use process variables to enforce permissions:

var initiator = execution.getVariable('InitiatedBy');
var userRole = doQuery('GetUserRoleQuery', { userId: initiator });

if (userRole !== 'MANAGER') {
  throw new Error('Unauthorized: Manager approval required');
}

Process Engine