Webhook Configuration APIs

Complete API reference for BankLingo's Webhook Configuration System.

Overview

Webhooks allow external systems to trigger actions in BankLingo. Configure webhook endpoints that can execute commands, run code, or start BPMN processes.

Base Endpoint

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

Webhook Endpoint

Once configured, webhooks are accessible at:

POST /api/webhook/{path}
Content-Type: application/json
X-Forwarded-For: {client-ip}  (optional)

Create Webhook

Create a new webhook configuration.

CreateWebHookConfigCommand

Request:

{
  "cmd": "CreateWebHookConfigCommand",
  "data": {
    "key": "paystack_callback",
    "description": "Paystack payment callback handler",
    "path": "paystack/callback",
    "action": "POST",
    "executionType": 0,
    "commandName": "ProcessPaystackWebhookCommand",
    "isEnabled": true,
    "allowableIPs": "52.31.139.75,52.49.173.169,52.214.14.220"
  }
}

Parameters:

Field	Type	Required	Description
`key`	string	Yes	Unique identifier for the webhook
`description`	string	No	Description of webhook purpose
`path`	string	Yes	URL path (accessible at `/api/webhook/{path}`)
`action`	string	Yes	HTTP method: `POST`, `GET`, `PUT`, `DELETE`, `PATCH`
`executionType`	number	Yes	0=Command, 2=Code, 3=Process
`commandName`	string	Conditional	Required if executionType=0 (Command)
`executionCode`	string	Conditional	Required if executionType=2 (Code)
`processDefinitionId`	number	Conditional	Required if executionType=3 (Process)
`isEnabled`	boolean	No	Enable/disable webhook (default: true)
`allowableIPs`	string	No	Comma-separated list of allowed IP addresses

Execution Types:

0 - ExecuteNativeCommand: Execute a command with webhook data
2 - ExecuteCode: Execute JavaScript code expression
3 - StartProcess: Start a BPMN process with webhook data

Response:

{
  "isSuccessful": true,
  "message": "Webhook created successfully",
  "data": {
    "id": 1,
    "key": "paystack_callback",
    "path": "paystack/callback",
    "url": "{BaseUrl}/api/webhook/paystack/callback",
    "executionType": 0,
    "isEnabled": true
  }
}

Example 1: Execute Command Webhook

Create Webhook:

{
  "cmd": "CreateWebHookConfigCommand",
  "data": {
    "key": "nibss_notification",
    "path": "nibss/notify",
    "action": "POST",
    "executionType": 0,
    "commandName": "ProcessNIBSSNotificationCommand",
    "isEnabled": true
  }
}

External System Calls Webhook:

curl -X POST https://your-bank.com/api/webhook/nibss/notify \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "SID-12345",
    "status": "SUCCESS",
    "amount": 50000
  }'

What Happens:

Webhook receives POST to /api/webhook/nibss/notify
Executes ProcessNIBSSNotificationCommand
Command receives webhook data as parameters
Returns command result to caller

Example 2: Execute Code Webhook

Create Webhook:

{
  "cmd": "CreateWebHookConfigCommand",
  "data": {
    "key": "simple_logger",
    "path": "events/log",
    "action": "POST",
    "executionType": 2,
    "executionCode": "doLog('Event received', { data: webhookData, ip: remoteIp }); return { ok: true, timestamp: new Date().toISOString() };",
    "isEnabled": true
  }
}

External System Calls Webhook:

curl -X POST https://your-bank.com/api/webhook/events/log \
  -H "Content-Type: application/json" \
  -d '{"event": "user.login", "userId": "12345"}'

Available Context Variables:

webhookData - Request body (parsed JSON)
webhookPath - URL path (e.g., "events/log")
webhookMethod - HTTP method (e.g., "POST")
remoteIp - Client IP address

Example 3: Start Process Webhook

Create Webhook:

{
  "cmd": "CreateWebHookConfigCommand",
  "data": {
    "key": "payment_callback",
    "path": "payment/callback",
    "action": "POST",
    "executionType": 3,
    "processDefinitionId": 42,
    "isEnabled": true
  }
}

External System Calls Webhook:

curl -X POST https://your-bank.com/api/webhook/payment/callback \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "PAY-12345",
    "status": "success",
    "amount": 100000,
    "transactionId": "TXN-987654"
  }'

What Happens:

Webhook receives POST data
Starts BPMN process (ID=42)

Process variables include webhook data:

webhookData = { reference: "PAY-12345", status: "success", ... }
webhookPath = "payment/callback"
webhookMethod = "POST"
remoteIp = "52.31.139.75"

Process can extract correlation key and call ReturnCallbackCommand

Example BPMN Process:

<bpmn:process id="PaymentCallbackHandler">
  <bpmn:scriptTask id="ExtractKey">
    <bpmn:script>
      var payload = webhookData;
      var correlationKey = payload.reference;
      var status = payload.status;
      execution.setVariable('correlationKey', correlationKey);
      execution.setVariable('isSuccess', status === 'success');
    </bpmn:script>
  </bpmn:scriptTask>
  
  <bpmn:serviceTask id="ReturnCallback" 
                    bankLingo:commandName="ReturnCallbackCommand">
    <bankLingo:inputParameter name="correlationKey">${correlationKey}</bankLingo:inputParameter>
    <bankLingo:inputParameter name="callbackData">${webhookData}</bankLingo:inputParameter>
    <bankLingo:inputParameter name="isSuccess">${isSuccess}</bankLingo:inputParameter>
  </bpmn:serviceTask>
</bpmn:process>

Update Webhook

Update an existing webhook configuration.

UpdateWebHookConfigCommand

Request:

{
  "cmd": "UpdateWebHookConfigCommand",
  "data": {
    "id": 1,
    "description": "Updated description",
    "executionCode": "doLog('Updated code'); return { ok: true };",
    "isEnabled": true
  }
}

Response:

{
  "isSuccessful": true,
  "message": "Webhook updated successfully",
  "data": {
    "id": 1,
    "key": "paystack_callback",
    "isEnabled": true
  }
}

Get Webhook By ID

Retrieve webhook details including execution code.

GetWebHookConfigByIdQuery

Request:

{
  "cmd": "GetWebHookConfigByIdQuery",
  "data": {
    "id": 1
  }
}

Response:

{
  "isSuccessful": true,
  "message": "Webhook data retrieved successfully",
  "data": {
    "id": 1,
    "key": "paystack_callback",
    "description": "Paystack payment callback",
    "path": "paystack/callback",
    "url": "{BaseUrl}/api/webhook/paystack/callback",
    "action": "POST",
    "executionType": 0,
    "executionTypeDesc": "Execute Native Command",
    "commandName": "ProcessPaystackWebhookCommand",
    "executionCode": null,
    "processDefinitionId": null,
    "isEnabled": true,
    "allowableIPs": "52.31.139.75,52.49.173.169",
    "createdAt": "2026-01-10T10:00:00Z",
    "updatedAt": "2026-01-11T09:00:00Z"
  }
}

List Webhooks

List all webhook configurations (excludes ExecutionCode for security).

GetWebHookConfigListQuery

Request:

{
  "cmd": "GetWebHookConfigListQuery",
  "data": {
    "pageIndex": 0,
    "pageSize": 20,
    "isEnabled": true
  }
}

Parameters:

Field	Type	Required	Description
`pageIndex`	number	No	Page index (default: 0)
`pageSize`	number	No	Page size (default: 20)
`isEnabled`	boolean	No	Filter by enabled status
`key`	string	No	Filter by webhook key

Response:

{
  "isSuccessful": true,
  "message": "20/50 records",
  "count": 50,
  "pages": 3,
  "size": 20,
  "hasNext": true,
  "data": [
    {
      "id": 1,
      "key": "paystack_callback",
      "path": "paystack/callback",
      "action": "POST",
      "commandName": "ProcessPaystackWebhookCommand",
      "executionType": 0,
      "executionTypeDesc": "Execute Native Command",
      "processDefinitionId": null,
      "isEnabled": true,
      "description": "Paystack payment callback",
      "allowableIPs": "52.31.139.75",
      "createdAt": "2026-01-10T10:00:00Z"
    },
    {
      "id": 2,
      "key": "nibss_notification",
      "path": "nibss/notify",
      "action": "POST",
      "commandName": null,
      "executionType": 3,
      "executionTypeDesc": "Start Process",
      "processDefinitionId": 42,
      "isEnabled": true,
      "createdAt": "2026-01-11T08:00:00Z"
    }
  ]
}

Note: executionCode is excluded from list for security.

Delete Webhook

Delete a webhook configuration.

DeleteWebHookConfigCommand

Request:

{
  "cmd": "DeleteWebHookConfigCommand",
  "data": {
    "id": 1
  }
}

Response:

{
  "isSuccessful": true,
  "message": "Webhook deleted successfully"
}

Activate/Deactivate Webhook

Enable or disable a webhook without deleting it.

ActivateWebHookConfigCommand

Request:

{
  "cmd": "ActivateWebHookConfigCommand",
  "data": {
    "id": 1
  }
}

DeactivateWebHookConfigCommand

Request:

{
  "cmd": "DeactivateWebHookConfigCommand",
  "data": {
    "id": 1
  }
}

Webhook Security

IP Whitelisting

Restrict webhook access to specific IP addresses:

{
  "allowableIPs": "52.31.139.75,52.49.173.169,52.214.14.220"
}

Multiple IPs: Separate with commas
IP Ranges: Not currently supported (use individual IPs)

If IP Not Whitelisted:

{
  "error": "The IP for the request has not been whitelisted"
}

Signature Verification

For additional security, verify webhook signatures in your command:

// In your webhook command handler
var receivedSignature = request.headers['X-Webhook-Signature'];
var webhookSecret = $.secure.get('PAYSTACK_SECRET');
var expectedSignature = hmacSha256(webhookSecret, requestBody);

if (receivedSignature !== expectedSignature) {
  throw new Error('Invalid webhook signature');
}

Error Handling

Webhook Not Found

{
  "error": "Webhook not configured.",
  "status": 404
}

Webhook Disabled

{
  "error": "Webhook is not active.",
  "status": 403
}

IP Not Allowed

{
  "error": "The IP for the request has not been whitelisted.",
  "status": 403
}

Configuration Error (Missing Required Field)

{
  "error": "Webhook configuration error: CommandName is required for ExecuteNativeCommand.",
  "status": 400
}

Complete Example: Payment Gateway Integration

Step 1: Create Webhook Configuration

{
  "cmd": "CreateWebHookConfigCommand",
  "data": {
    "key": "paystack_webhook",
    "description": "Paystack payment callback for loan disbursement",
    "path": "paystack/callback",
    "action": "POST",
    "executionType": 3,
    "processDefinitionId": 50,
    "isEnabled": true,
    "allowableIPs": "52.31.139.75,52.49.173.169,52.214.14.220"
  }
}

Step 2: Configure Paystack Webhook

In Paystack dashboard, set webhook URL:

https://your-bank.com/api/webhook/paystack/callback

Step 3: Create BPMN Callback Handler (Process ID=50)

<bpmn:process id="PaystackCallbackHandler">
  <bpmn:startEvent id="Start"/>
  
  <bpmn:scriptTask id="ExtractData" name="Extract Callback Data">
    <bpmn:script>
      var payload = webhookData;
      var reference = payload.data.reference;
      var status = payload.event === 'charge.success';
      
      execution.setVariable('correlationKey', reference);
      execution.setVariable('isSuccess', status);
      execution.setVariable('transactionId', payload.data.id);
    </bpmn:script>
  </bpmn:scriptTask>
  
  <bpmn:serviceTask id="ReturnCallback" name="Resume Parent Process"
                    bankLingo:commandName="ReturnCallbackCommand">
    <bpmn:extensionElements>
      <bankLingo:inputParameter name="correlationKey">${correlationKey}</bankLingo:inputParameter>
      <bankLingo:inputParameter name="callbackData">${webhookData}</bankLingo:inputParameter>
      <bankLingo:inputParameter name="isSuccess">${isSuccess}</bankLingo:inputParameter>
    </bpmn:extensionElements>
  </bpmn:serviceTask>
  
  <bpmn:endEvent id="End"/>
</bpmn:process>

Step 4: Main Loan Process (Waits for Payment)

<bpmn:process id="LoanDisbursementProcess">
  <!-- ... loan approval steps ... -->
  
  <bpmn:serviceTask id="InitiatePayment" name="Initiate Paystack Payment">
    <bankLingo:commandName>InitiatePaystackPaymentCommand</bankLingo:commandName>
    <bankLingo:inputParameter name="amount">${loanAmount}</bankLingo:inputParameter>
    <bankLingo:inputParameter name="reference">${instanceId}-payment</bankLingo:inputParameter>
  </bpmn:serviceTask>
  
  <bpmn:receiveTask id="WaitForPayment" name="Wait for Payment Confirmation">
    <bpmn:extensionElements>
      <bankLingo:correlationKey>${instanceId}-payment</bankLingo:correlationKey>
    </bpmn:extensionElements>
  </bpmn:receiveTask>
  
  <!-- Process continues after Paystack webhook calls ReturnCallbackCommand -->
</bpmn:process>

Flow:

Loan process initiates Paystack payment with reference {instanceId}-payment
Loan process pauses at ReceiveTask waiting for correlation key
Customer completes payment on Paystack
Paystack sends webhook to /api/webhook/paystack/callback
Webhook starts PaystackCallbackHandler process (ID=50)
Process extracts reference and calls ReturnCallbackCommand
Loan process resumes with payment confirmation data

Best Practices

1. Use Unique Keys

{
  "key": "paystack_loan_disbursement_v2"
}

2. Always Set IP Whitelist

{
  "allowableIPs": "52.31.139.75,52.49.173.169"
}

3. Use Process Execution for Complex Logic

Don't put complex logic in ExecuteCode - use StartProcess instead:

✅ Process: Error handling, logging, multiple steps
❌ Code: Complex transformations, business rules

4. Test with Disabled Webhooks

Create webhooks disabled, test, then activate:

{
  "isEnabled": false  // Test first
}

5. Document Webhook Purpose

{
  "description": "Paystack payment callback for loan disbursement. Resumes LoanDisbursementProcess with payment confirmation."
}

Last Updated: January 11, 2026

Overview​

Base Endpoint​

Webhook Endpoint​

Create Webhook​

CreateWebHookConfigCommand​

Example 1: Execute Command Webhook​

Example 2: Execute Code Webhook​

Example 3: Start Process Webhook​

Update Webhook​

UpdateWebHookConfigCommand​

Get Webhook By ID​

GetWebHookConfigByIdQuery​

List Webhooks​

GetWebHookConfigListQuery​

Delete Webhook​

DeleteWebHookConfigCommand​

Activate/Deactivate Webhook​

ActivateWebHookConfigCommand​

DeactivateWebHookConfigCommand​

Webhook Security​

IP Whitelisting​

Signature Verification​

Error Handling​

Webhook Not Found​

Webhook Disabled​

IP Not Allowed​

Configuration Error (Missing Required Field)​

Complete Example: Payment Gateway Integration​

Step 1: Create Webhook Configuration​

Step 2: Configure Paystack Webhook​

Step 3: Create BPMN Callback Handler (Process ID=50)​

Step 4: Main Loan Process (Waits for Payment)​

Flow:​

Best Practices​

1. Use Unique Keys​

2. Always Set IP Whitelist​

3. Use Process Execution for Complex Logic​

4. Test with Disabled Webhooks​

5. Document Webhook Purpose​

Related Documentation​

Overview

Base Endpoint

Webhook Endpoint

Create Webhook

CreateWebHookConfigCommand

Example 1: Execute Command Webhook

Example 2: Execute Code Webhook

Example 3: Start Process Webhook

Update Webhook

UpdateWebHookConfigCommand

Get Webhook By ID

GetWebHookConfigByIdQuery

List Webhooks

GetWebHookConfigListQuery

Delete Webhook

DeleteWebHookConfigCommand

Activate/Deactivate Webhook

ActivateWebHookConfigCommand

DeactivateWebHookConfigCommand

Webhook Security

IP Whitelisting

Signature Verification

Error Handling

Webhook Not Found

Webhook Disabled

IP Not Allowed

Configuration Error (Missing Required Field)

Complete Example: Payment Gateway Integration

Step 1: Create Webhook Configuration

Step 2: Configure Paystack Webhook

Step 3: Create BPMN Callback Handler (Process ID=50)

Step 4: Main Loan Process (Waits for Payment)

Flow:

Best Practices

1. Use Unique Keys

2. Always Set IP Whitelist

3. Use Process Execution for Complex Logic

4. Test with Disabled Webhooks

5. Document Webhook Purpose

Related Documentation