Skip to main content

​
Event

flows.tasks.step_change
This event fires each time a task transitions from one step to another — for example, when an approver completes their step and the task moves to the next assignee.

​
Payload Example

{
  "event": "flows.tasks.step_change",
  "event_id": "evt_01HXYZ8899001122",
  "organization_id": "org_abc123",
  "timestamp": "2025-06-06T10:30:00Z",
  "data": {
    "task_id": "task_def456",
    "workflow_id": "wf_contract_review",
    "workflow_name": "Contract Review",
    "previous_step": {
      "step_id": "step_1",
      "step_name": "Initial Review",
      "completed_by": "reviewer@example.com",
      "completed_at": "2025-06-06T10:29:55Z",
      "outcome": "approved"
    },
    "current_step": {
      "step_id": "step_2",
      "step_name": "Legal Approval",
      "assignee": "legal@example.com"
    }
  }
}

​
Payload Fields

​
Envelope

FieldTypeDescription
eventstringAlways flows.tasks.step_change
event_idstringUnique delivery ID — use to deduplicate retries
organization_idstringID of the organization
timestampstringISO 8601 UTC timestamp of the event
dataobjectEvent-specific payload (see below)

​
Data Object

FieldTypeDescription
task_idstringUnique identifier of the task
workflow_idstringID of the parent workflow
workflow_namestringHuman-readable workflow name
previous_stepobjectDetails of the step that was just completed
current_stepobjectDetails of the step the task moved into

​
Previous Step Object

FieldTypeDescription
step_idstringUnique identifier of the completed step
step_namestringHuman-readable step name
completed_bystringEmail of the user who completed the step
completed_atstringISO 8601 UTC timestamp of completion
outcomestringStep outcome (e.g., approved, rejected, submitted)

​
Current Step Object

FieldTypeDescription
step_idstringUnique identifier of the new step
step_namestringHuman-readable step name
assigneestringEmail of the user assigned to this step