Events & Signals

JustWorkflowIt workflows can pause and wait for external signals using the WaitForEventIds step executor. This enables approval gates, webhook callbacks, and human-in-the-loop workflows.

How It Works

1. A workflow step uses /justworkflowit/waitForEventIds with one or more expected event IDs
2. The job enters a waiting state (RUNNING with status successful_but_incomplete)
3. An external system calls SendJobEvent with the matching eventId
4. The engine records the event and advances to the next step

Example: Approval Gate

{
  "workflowName": "approval-flow",
  "steps": [
    {
      "name": "requestApproval",
      "integrationDetails": {
        "type": "/justworkflowit/aws/lambda",
        "config": {
          "region": "us-east-1",
          "accountId": "123456789012",
          "functionName": "send-approval-request"
        },
        "inputDefinition": { "$ref": "#/definitions/workflowInput" },
        "outputDefinition": { "$ref": "#/definitions/emptyDef" }
      },
      "transitionToStep": "waitForApproval"
    },
    {
      "name": "waitForApproval",
      "integrationDetails": {
        "type": "/justworkflowit/waitForEventIds",
        "config": { "eventIds": ["manager-approved"] },
        "inputDefinition": { "$ref": "#/definitions/emptyDef" },
        "outputDefinition": { "$ref": "#/definitions/approvalResult" }
      },
      "transitionToStep": "deploy"
    },
    {
      "name": "deploy",
      "integrationDetails": {
        "type": "/justworkflowit/aws/lambda",
        "config": {
          "region": "us-east-1",
          "accountId": "123456789012",
          "functionName": "run-deployment"
        },
        "inputDefinition": { "$ref": "#/definitions/approvalResult" },
        "outputDefinition": { "$ref": "#/definitions/emptyDef" }
      },
      "transitionToStep": null
    }
  ],
  "definitions": {
    "workflowInput": { "type": "object", "properties": { "prId": { "type": "string" } }, "required": ["prId"], "additionalProperties": false },
    "emptyDef": { "type": "object", "properties": {}, "required": [], "additionalProperties": false },
    "approvalResult": { "type": "object", "properties": { "approved": { "type": "boolean" } }, "required": ["approved"], "additionalProperties": false }
  }
}

When the manager approves:

curl -X POST .../jobs/$JOB_ID/events \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"eventId": "manager-approved"}'

Multiple Events

A single WaitForEventIds step can wait for multiple events. The step completes only after all listed event IDs have been received.