A bike rental wants the rental contract printed at the shop counter as soon as someone books online. The booking workflow runs in AWS Step Functions. The printer hangs off a PC behind a cheap internet router that accepts no inbound connections. How does the workflow get the job to that PC?
Most teams would reach for a callback with a task token and a queue in between. In Step Functions Activity vs. Callback: When to Poll I argue that there is a leaner option for exactly this case: the Step Functions activity. Here is the gist.
Push versus pull
Both patterns rely on the same thing under the hood: a task token that identifies a waiting execution. The difference is how the work reaches the worker.
With a .waitForTaskToken callback, Step Functions pushes the task out through an integration, for example SQS, Lambda or EventBridge. With an activity, the worker pulls it. An activity is little more than a name with an ARN. The worker calls GetActivityTask, receives the input plus a token, and later answers with SendTaskSuccess or SendTaskFailure, sending SendTaskHeartbeat in between for longer jobs.
The call uses long polling: Step Functions holds the request open for up to 60 seconds and answers as soon as a task appears. A waiting worker costs almost nothing and still reacts quickly. And it only needs outbound HTTPS: no open ports, no port forwarding, no VPN.
When polling is the better choice
I reach for an activity in two situations: workers that AWS cannot and should not reach (a shop PC, a machine on a factory floor, a server in your own data center), and long-running containers or special hardware that runs around the clock anyway. In both cases you skip the queue and have one less moving part.
I stick with the callback when the worker is a Lambda function (polling in a loop means paying for every second of waiting), or when I need what a queue offers: a dead-letter queue, redrive, fan-out or queue-length metrics. And note that Express workflows support neither option.
A minimal poll loop looks roughly like this. The important detail is the client timeout, which should be at least 65 seconds:
const sfn = new SFNClient({
requestHandler: new NodeHttpHandler({ requestTimeout: 70_000 }),
});
while (running) {
const task = await sfn.send(new GetActivityTaskCommand({ activityArn, workerName }));
if (!task.taskToken) continue; // empty poll after up to 60 s
const result = await printContract(JSON.parse(task.input ?? "{}"));
await sfn.send(new SendTaskSuccessCommand({
taskToken: task.taskToken,
output: JSON.stringify(result),
}));
}
The real worker in the article adds several pollers, a concurrency limit, heartbeats and error handling.
Where tasks get stuck
The simplicity has a price: polling, heartbeats, shutdown and idempotency are entirely your job. The traps I would watch first:
- Short client timeouts or proxies that cut idle connections make empty polls fail and can lose tokens.
-
No
TimeoutSecondson the task state means an execution may wait until the maximum run time, which is a year for standard workflows, if no worker is running. - Cutting off polls on shutdown can drop a token that was just being assigned. Let open polls return on their own.
- Retries after a heartbeat timeout can print the contract twice. Make the work idempotent.
- Changing the input format of an existing activity breaks old workers, because activities are not versioned.
AWS also recommends keeping at least 100 polls open per activity ARN for production systems. For a shop PC with a few contracts per hour that is oversized, but for a throughput worker in ECS it is worth calculating.
My advice in one line: use activities at the edges of your system, and stay with events at its core.
What the full article covers
- A comparison table of activity and callback, plus the full decision guide
- A CDK stack with the activity, state machine, scoped IAM role and CloudWatch alarm
- The complete TypeScript worker with pollers, heartbeats,
AbortSignaland clean shutdown - Vitest tests without an AWS account, throttling limits, and security tips such as IAM Roles Anywhere
Everything, including the runnable code: Step Functions Activity vs. Callback: When to Poll
📖 This is the condensed version. The full article on sascha-ms.de goes deeper – with all code samples, diagrams and a short knowledge check.
👉 Next step: Working with AWS CDK? Grab my printable AWS CDK cheat sheet with commands, concepts and a stack skeleton.
📬 Stay updated: New articles on serverless, AI and leading tech teams via RSS, browser push or the weekly newsletter (in German).
Originally published on sascha-ms.de. More articles on serverless, AI in everyday development and leading tech teams: sascha-ms.de/en
Top comments (0)