Skip to main content

Return Callback

Overview​

The ReturnCallbackCommand resumes a paused process by returning results from a callback. This command handles two types of callbacks:

  1. Subprocess Callbacks (CallActivity) - Parent process waits for child subprocess to complete
  2. External Callbacks (ReceiveTask) - Process waits for webhook, payment gateway, or third-party API response
Also see SignalProcessInstanceCommand

For ReceiveTask callbacks, you can also use SignalProcessInstanceCommand which supports both instanceGuid and correlationKey lookup, and also handles UserTask signals. ReturnCallbackCommand is primarily needed for CallActivity (subprocess) callbacks.

API Endpoint​

POST /api/core/cmd

Headers​

Content-Type: application/json
Authorization: Bearer {access_token}
X-Tenant-ID: {tenant_id}

Request Structure​

Format 1: By Child Instance ID (Subprocess / CallActivity)​

Use when a child subprocess completes and needs to return results to the parent process.

{
  "cmd": "ReturnCallbackCommand",
  "data": {
    "childInstanceId": "subprocess-abc-123",
    "results": {
      "creditScore": 750,
      "riskLevel": "LOW",
      "approved": true
    }
  }
}

Format 2: By Correlation Key (External Webhook / ReceiveTask)​

Use when an external system posts a webhook callback identified by a correlation key.

{
  "cmd": "ReturnCallbackCommand",
  "data": {
    "correlationKey": "TXN-987654",
    "results": {
      "status": "success",
      "transactionRef": "FT-20260210-001",
      "amount": 50000,
      "currency": "NGN"
    }
  }
}

Format 3: Reporting a Failure​

Use to signal that the external operation failed.

{
  "cmd": "ReturnCallbackCommand",
  "data": {
    "correlationKey": "TXN-987654",
    "isFailed": true,
    "errorMessage": "Payment gateway timeout after 30 seconds",
    "results": {
      "gatewayCode": "TIMEOUT",
      "retryable": true
    }
  }
}