A Step Functions activity might be the most underrated feature in AWS Step Functions. Most teams know the callback with a task token: the workflow drops a message with a token into a queue, and some worker reports back later with the result. An activity flips that around. The worker asks for work on its own, picks it up and reports the result. No queue, no inbound connection, just outbound HTTPS.

In my post on Step Functions timeouts and heartbeats, activities only got a passing mention. I want to fix that here, because the question “activity or callback?” keeps coming up in architecture discussions and rarely gets a clean answer. You get the differences, a clear decision guide and a complete TypeScript worker you can try right away.

In short

A Step Functions activity is a queue with an ARN: the workflow places a task there, a worker fetches it via long polling and reports the result back with the task token. That fits especially well for workers that cannot accept inbound connections, such as computers in a retail shop or containers that run all the time. The biggest pitfall is polling itself: too few open polls, polls cut off during shutdown and missing timeouts lead to tasks that hang for minutes.

What you will learn in this article

  • How a Step Functions activity works and how it differs from a callback
  • When a polling worker pays off and when a callback is the better choice
  • How to set up the activity, state machine and alarm with AWS CDK
  • What a TypeScript worker with several pollers, heartbeats and clean shutdown looks like
  • Which typical mistakes leave tasks hanging

What is a Step Functions activity?

In Step Functions, an activity is first of all just a name with an ARN. It contains no code and no runtime. You create it (in the console, with the CLI or as infrastructure as code) and reference its ARN in the Resource field of a task state. When an execution reaches that state, Step Functions schedules a task and waits.

The actual work is done by a so-called activity worker. That can be any program able to open HTTPS connections to AWS: a process on an EC2 instance, a container in ECS, a computer in the office or a mini PC in a shop. The worker calls the GetActivityTask API and receives two things: the input as a JSON string and a task token. Later it uses this token to report back via SendTaskSuccess or SendTaskFailure. For longer jobs it sends SendTaskHeartbeat in between as a sign of life.

Long polling in a nutshell

GetActivityTask uses long polling. In other words, the request does not return empty right away when there is nothing to do. Step Functions keeps the connection open for up to 60 seconds and answers as soon as a task shows up. If nothing arrives in that time, the API returns an empty task token and the worker simply asks again. A waiting worker therefore uses hardly any compute time, and new tasks still arrive with almost no delay.

Activity or callback: the difference

Both patterns use the same mechanism under the hood: a task token that uniquely identifies a waiting execution. The difference lies in how the task reaches the worker. With a .waitForTaskToken callback, Step Functions pushes the work out through an integration, for example as an SQS message, a Lambda invocation or an EventBridge event, and includes the token from the context object ($$.Task.Token). With an activity, the worker pulls the work itself.

Diagram: a callback with task token pushes work via SQS/Lambda, while an activity worker fetches it via GetActivityTask

Callback and activity compared: who moves the task to the worker?

In day-to-day use, the two options differ in a few points that matter for your decision:

Criterion Step Functions activity Callback with task token
Who moves the task? The worker fetches it with GetActivityTask Step Functions sends it through an integration
Extra resource None, just the activity itself Queue, topic, event bus or function
Lambda as worker Poor fit, because Lambda would have to poll constantly Great fit, for example via SQS with an event source mapping
Buffering and dead-letter queue No DLQ of its own, tasks wait in the activity Everything SQS or EventBridge offers
Express workflows Not supported Not supported
Typical use Long-running workers without inbound connections Event-driven processing, approvals, third-party systems

One point is often overlooked: a callback via SQS is a pull for the worker as well. It reads from the queue, after all. So the real difference is whether there is one more service between Step Functions and the worker that you have to run, monitor and pay for. With an activity, Step Functions takes on the role of the queue as well.

When a Step Functions activity pays off

I reach for an activity when at least one of the following cases applies. If none of them does, the callback with a task token is usually the better choice.

Workers without inbound connections

The classic case is a computer that AWS cannot reach and should not reach: a PC in a retail shop behind a router, a machine on a factory floor or a server in your own data center. The worker only needs outbound HTTPS to the Step Functions endpoint. There are no open ports, no port forwarding and no VPN tunnel. For many security teams, that is a strong argument.

Long-running containers and special hardware

If your worker runs around the clock anyway, say an ECS service with lots of memory or an EC2 instance with a GPU, polling costs practically nothing extra. You skip the queue in between and have one less mechanism that can go wrong.

When to stick with the callback

If the worker should be a Lambda function, use the callback. A Lambda function that polls in a loop pays for every second of waiting. AWS itself points out in its best practices that 100 polling functions cost a hundred times as much as one function with 100 polling threads. You should also stay with the callback if you need the strengths of a queue: a dead-letter queue, redrive, fan-out to several receivers or metrics on queue length. Not sure which service fits at all? The AWS service finder helps with a rough first choice.

🎬 How a Step Functions activity flows – this animated diagram only runs on my site: watch it on sascha-ms.de

The example: printing contracts at a bike rental

For the example, we stay with the fictional bike rental “Speichenwerk”. When someone books a bike online, a workflow starts. One of its steps prints the rental contract on the printer at the shop counter. The printer is attached to the shop PC, and the shop PC sits behind a simple internet router that allows no inbound connections.

This is exactly where a Step Functions activity fits. In the morning, the shop PC starts a small Node.js worker that polls the activity speichenwerk-print-contract. When a task comes in, it prints the contract, sends heartbeats while doing so and reports the result. If the PC fails, Step Functions notices the missing heartbeat after 30 seconds and schedules the task again.

Step by step: Step Functions activity with CDK and TypeScript

You build the infrastructure with AWS CDK and the worker with TypeScript and the AWS SDK for JavaScript v3. I checked all files with tsc --noEmit, cdk synth and Vitest.

Prerequisites

  • Node.js 22 or newer and npm
  • An AWS account where you may create Step Functions, IAM and CloudWatch resources
  • AWS CLI v2 with a configured profile
  • Basic knowledge of Step Functions (states, executions)

Step 1: Create the project

Create an empty directory and install the dependencies. These are the versions I used to test the example.

mkdir speichenwerk-activity && cd speichenwerk-activity npm init -y npm install @aws-sdk/client-sfn@3.1169.0 @smithy/node-http-handler@4.14.2 npm install -D aws-cdk-lib@2.277.0 aws-cdk@2.1148.1 constructs@10.8.1 typescript@7.0.2 tsx@4.23.15 vitest@5.1.0 aws-sdk-client-mock@4.1.0 @types/node@26.6.6 mkdir bin lib src test 

In package.json, add "type": "module" and the scripts "test": "vitest run" and "worker": "tsx src/main.ts". The tsconfig.json and cdk.json look like this:

{ "compilerOptions": { "target": "ES2023", "module": "NodeNext", "moduleResolution": "NodeNext", "strict": true, "esModuleInterop": true, "skipLibCheck": true, "types": ["node"] }, "include": ["bin", "lib", "src", "test"] } 
{ "app": "npx tsx bin/app.ts" } 

Step 2: The CDK stack

The stack creates four things: the activity, a standard state machine with the print step, an IAM role for the shop PC and a CloudWatch alarm.

// lib/contract-print-stack.ts import { CfnOutput, Duration, Stack, type StackProps } from 'aws-cdk-lib'; import * as cloudwatch from 'aws-cdk-lib/aws-cloudwatch'; import * as iam from 'aws-cdk-lib/aws-iam'; import * as sfn from 'aws-cdk-lib/aws-stepfunctions'; import * as tasks from 'aws-cdk-lib/aws-stepfunctions-tasks'; import type { Construct } from 'constructs'; export class ContractPrintStack extends Stack { constructor(scope: Construct, id: string, props?: StackProps) { super(scope, id, props); // The activity is just a "queue with an ARN" – it contains no code const printActivity = new sfn.Activity(this, 'PrintContractActivity', { activityName: 'speichenwerk-print-contract', }); const prepare = new sfn.Pass(this, 'PrepareContract', { parameters: { 'rentalId.$': '$.rentalId', 'customerName.$': '$.customerName', 'bikeId.$': '$.bikeId', }, }); const printContract = new tasks.StepFunctionsInvokeActivity(this, 'PrintContract', { activity: printActivity, // No sign of life for 30 s means the worker is considered lost heartbeatTimeout: sfn.Timeout.duration(Duration.seconds(30)), // Hard upper limit, including the wait time in the activity queue taskTimeout: sfn.Timeout.duration(Duration.minutes(10)), resultPath: '$.print', }); printContract.addRetry({ errors: ['States.HeartbeatTimeout'], maxAttempts: 2, interval: Duration.seconds(5), backoffRate: 2, }); const printFailed = new sfn.Fail(this, 'PrintFailed', { error: 'ContractNotPrinted', cause: 'The rental contract could not be printed', }); printContract.addCatch(printFailed, { resultPath: '$.error' }); const stateMachine = new sfn.StateMachine(this, 'RentalCheckout', { stateMachineName: 'speichenwerk-rental-checkout', definitionBody: sfn.DefinitionBody.fromChainable( prepare.next(printContract).next(new sfn.Succeed(this, 'ReadyForPickup')), ), stateMachineType: sfn.StateMachineType.STANDARD, timeout: Duration.minutes(30), }); // Role for the shop PC: may only poll and answer this one activity const workerRole = new iam.Role(this, 'ShopWorkerRole', { assumedBy: new iam.AccountRootPrincipal(), description: 'Activity worker in the shop (print station)', }); printActivity.grant( workerRole, 'states:GetActivityTask', 'states:SendTaskSuccess', 'states:SendTaskFailure', 'states:SendTaskHeartbeat', ); // Tasks waiting longer than 60 s for a worker? Workers are missing or overloaded printActivity .metricScheduleTime({ statistic: 'Maximum', period: Duration.minutes(5) }) .createAlarm(this, 'WorkerMissingAlarm', { threshold: 60_000, evaluationPeriods: 1, treatMissingData: cloudwatch.TreatMissingData.NOT_BREACHING, alarmDescription: 'Print tasks are waiting too long for the shop worker', }); new CfnOutput(this, 'ActivityArn', { value: printActivity.activityArn }); new CfnOutput(this, 'StateMachineArn', { value: stateMachine.stateMachineArn }); new CfnOutput(this, 'WorkerRoleArn', { value: workerRole.roleArn }); } } 
// bin/app.ts import { App } from 'aws-cdk-lib'; import { ContractPrintStack } from '../lib/contract-print-stack.js'; const app = new App(); new ContractPrintStack(app, 'ContractPrintStack'); 

A few places deserve a second look. The PrintContract state has two time limits. heartbeatTimeout with 30 seconds detects a crashed worker quickly. taskTimeout with ten minutes limits the total duration of the state, including the time a task waits for a free worker. Without this limit and without an overall timeout on the state machine, an execution would wait until the maximum run time if the shop PC is switched off. For standard workflows that is one year.

The retry on States.HeartbeatTimeout schedules the task again after a crash, so another worker (or the same one after a restart) can take over. All other errors go through the catch into the PrintFailed state.

The ShopWorkerRole may only poll and answer this single activity. The alarm uses the ActivityScheduleTime metric, which is the time a task stays scheduled before a worker picks it up. If it rises above one minute, the workers cannot keep up or only run part of the time. If no worker runs at all, a task is never picked up. That is why you should also monitor the ActivitiesTimedOut metric or failed executions.

Step 3: The print logic

The print logic is deliberately simple. It validates the input and simulates printing with a delay. The AbortSignal matters here: if the task token expires, printing stops cleanly instead of carrying on into the void.

// src/print-contract.ts import { setTimeout as sleep } from 'node:timers/promises'; export interface PrintJob { rentalId: string; customerName: string; bikeId: string; } export class InvalidPrintJobError extends Error { override readonly name = 'InvalidPrintJob'; } export function parsePrintJob(input: unknown): PrintJob { const job = input as Partial<PrintJob> | null; for (const field of ['rentalId', 'customerName', 'bikeId'] as const) { if (typeof job?.[field] !== 'string' || job[field].length === 0) { throw new InvalidPrintJobError(`Field "${field}" is missing or empty`); } } return job as PrintJob; } // Simulates the printer at the shop counter (takes a few seconds) export async function printContract(input: unknown, signal: AbortSignal) { const job = parsePrintJob(input); const printMs = Number(process.env.PRINT_DURATION_MS ?? 3000); await sleep(printMs, undefined, { signal }); return { rentalId: job.rentalId, printer: process.env.PRINTER_NAME ?? 'counter-1', printedAt: new Date().toISOString(), }; } 

The custom error type InvalidPrintJob later ends up as the error name in SendTaskFailure. That lets you react to it specifically in the state machine, for example with a dedicated catch that reports the case to the counter.

Step 4: The activity worker

Now for the core piece. The worker starts several poll loops in parallel and at the same time limits how many tasks it processes at once. Each task gets its own heartbeat interval.

// src/activity-worker.ts import { GetActivityTaskCommand, SendTaskFailureCommand, SendTaskHeartbeatCommand, SendTaskSuccessCommand, SFNClient, TaskTimedOut, } from '@aws-sdk/client-sfn'; import { NodeHttpHandler } from '@smithy/node-http-handler'; import { Agent } from 'node:https'; import { setTimeout as sleep } from 'node:timers/promises'; export type JobHandler = (input: unknown, signal: AbortSignal) => Promise<unknown>; export interface WorkerOptions { activityArn: string; workerName: string; /** How many GetActivityTask calls may be open at the same time */ pollers: number; /** How many tasks the machine processes at the same time */ maxParallelJobs: number; /** Heartbeat interval, well below heartbeatTimeout */ heartbeatMs: number; } export function createSfnClient(region?: string, maxSockets = 50): SFNClient { return new SFNClient({ region, requestHandler: new NodeHttpHandler({ connectionTimeout: 5_000, // Step Functions holds a poll open for up to 60 s – leave some headroom requestTimeout: 70_000, httpsAgent: new Agent({ keepAlive: true, maxSockets }), }), }); } class Slots { private waiters: Array<() => void> = []; constructor(private free: number) {} async acquire(): Promise<void> { if (this.free > 0) { this.free--; return; } await new Promise<void>((resolve) => this.waiters.push(resolve)); } release(): void { const next = this.waiters.shift(); if (next) next(); else this.free++; } } export class ActivityWorker { private stopping = false; private readonly running = new Set<Promise<void>>(); private readonly slots: Slots; constructor( private readonly client: SFNClient, private readonly opts: WorkerOptions, private readonly handler: JobHandler, ) { this.slots = new Slots(opts.maxParallelJobs); } async run(): Promise<void> { const loops = Array.from({ length: this.opts.pollers }, (_, i) => this.pollLoop(i)); await Promise.all(loops); await Promise.allSettled([...this.running]); } /** Start no new polls; let running polls and tasks finish cleanly */ stop(): void { this.stopping = true; } private async pollLoop(index: number): Promise<void> { let failures = 0; while (!this.stopping) { // Only poll when we can process a task right away await this.slots.acquire(); if (this.stopping) { this.slots.release(); break; } let taskToken: string | undefined; let input = '{}'; try { const task = await this.client.send( new GetActivityTaskCommand({ activityArn: this.opts.activityArn, workerName: `${this.opts.workerName}-${index}`, }), ); taskToken = task.taskToken || undefined; input = task.input ?? '{}'; failures = 0; } catch (err) { this.slots.release(); failures++Source:https://dev.to/sascha-ms/step-functions-activity-vs-callback-when-to-poll-eci

Related posts