Consume and route events

An event handler is a registered rule that consumes messages from a broker and turns them into workflow actions. When a message arrives on the queue the handler watches, the handler evaluates its condition against the payload and can start a new workflow, or complete or fail one specific task. Handlers are how outside systems drive workflows without calling the Conductor API themselves.

Register a handler

Create and activate the handler with the Event Handlers API. Its event is provider:<provider-specific queue URI>; runtime parsing splits at the first colon. The provider must be enabled on the server.

On Orkes, first configure the managed broker integration, then use that configured integration in the event-handler flow. The OSS API example below uses an OSS provider key and enabled server module; it is not an integration-setup example.

{
  "name": "start_fulfillment_on_order_ready",
  "event": "conductor:publish_order_event:order-status",
  "condition": "$.status == 'READY'",
  "actions": [
    {
      "action": "start_workflow",
      "start_workflow": {
        "name": "fulfill_order",
        "version": 1,
        "correlationId": "${orderId}",
        "input": {
          "orderId": "${orderId}",
          "sourceEventId": "${workflowInstanceId}"
        }
      }
    }
  ],
  "active": true
}

Match the payload, not a wrapper

Conditions and placeholders are rooted directly at the delivered payload. For example, use $.status == 'READY' in a condition and ${orderId} in an action. A missing condition is true; active defaults to false.

If evaluatorType names a registered evaluator, Conductor uses it. Otherwise it uses the default script evaluator. Set expandInlineJSON: true on an action only when fields inside the event are intentionally JSON strings that must be expanded before expressions resolve.

Choose an action

Action	OSS Conductor	Orkes	Behavior
start_workflow	Yes	Yes	Starts a named workflow and includes Conductor event metadata in its input.
complete_task	Yes	Yes	Completes one identified task.
fail_task	Yes	Yes	Fails one identified task and can set reasonForIncompletion.
terminate_workflow	No	Yes	Terminates the targeted workflow.
update_workflow_variables	No	Yes	Updates variables on the targeted workflow.

Task actions need an exact target: provide taskId, or both workflowId and taskRefName. A business correlation key alone cannot resolve an OSS handler action to a waiting task.

Complete or fail a targeted task

Use a task action when the event itself supplies the task identity. The handler resolves placeholders from the broker payload.

Complete the task when the approval event arrives:

{
  "name": "complete_payment_wait",
  "event": "kafka:payment-events",
  "condition": "$.status == 'APPROVED'",
  "actions": [
    {
      "action": "complete_task",
      "complete_task": {
        "workflowId": "${workflowId}",
        "taskRefName": "wait_for_payment",
        "output": {
          "paymentId": "${paymentId}",
          "approved": true
        }
      }
    }
  ],
  "active": true
}

Register a separate handler for a rejected event when it should fail a task:

{
  "name": "fail_payment_wait",
  "event": "kafka:payment-events",
  "condition": "$.status == 'REJECTED'",
  "actions": [
    {
      "action": "fail_task",
      "fail_task": {
        "taskId": "${rejectionTaskId}",
        "reasonForIncompletion": "${reason}",
        "output": {
          "providerStatus": "${status}"
        }
      }
    }
  ],
  "active": true
}

Delivery and idempotency

Actions execute concurrently and are not atomic. Conductor records each action with the broker message ID and action index; a stable message ID enables persisted duplicate detection after the event execution is stored. Still make workflow starts, task updates, and any external side effects idempotent. When a condition is false, Conductor records a skipped event execution and runs no actions.

Next steps

Publish an event → Receive an HTTP callback → Event handler reference → Signal a known waiting workflow →