Recommended Free Tools
iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
When an external service finishes work later, use a Step Functions callback task with .waitForTaskToken rather than holding an HTTP request open. Step Functions pauses a Standard Workflow until an authorized caller returns the task token using SendTaskSuccess or SendTaskFailure. This separates the workflow’s wait from the external service’s request and lets you set explicit timeout, liveness, and retry behavior.
How the callback pattern works
A callback task creates a task token and hands it to an external worker or service. The workflow remains paused while that system performs its work. When the work finishes, the callback caller sends the token to Step Functions with either a success result or failure details; Step Functions then resumes or fails the waiting task.
- Step Functions starts the task. The task state creates a token available through the Context object.
- Your integration hands off the token. For example, API Gateway can send it in a request header, or a queue message can carry it to a worker.
- The external system performs the work. It should retain the token securely for the duration of the task.
- An authorized caller completes the task. It calls
SendTaskSuccesswith a result orSendTaskFailurewith failure information. - The workflow continues. Its next state receives the successful task result, or its error-handling path runs.
The callback must come from a principal in the same AWS account as the Step Functions task. See AWS’s service integration patterns documentation for token behavior and integration constraints.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Choose a callback, request-response, or job integration
Step Functions integrations generally use one of three patterns: request-response, run-a-job (.sync) or callback (.waitForTaskToken). Request-response continues when the integrated service returns its response; it does not mean the workflow waits for a later business event. A job integration waits for a supported service job. A callback is suited to work whose completion is controlled by an external system or does not fit a synchronous request.
#1 Best Overall
Direct HTTP Tasks are not a way to keep an HTTP request open for an arbitrarily long operation: AWS documents a maximum HTTP Task timeout of 60 seconds, even when a larger state timeout is requested. By contrast, callback tasks can wait up to the Step Functions one-year service quota, subject to the task’s own timeout and heartbeat settings. These are AWS service limits, not recommended target durations; check the current Task state documentation and integration pattern documentation when setting limits.
Workflow type matters
Callback-token integrations are supported by Standard Workflows where the chosen integration supports them. Express Workflows support request-response integrations only, so they are not suitable when a workflow must pause for a .waitForTaskToken callback. Verify the integration-pattern support for the specific service before committing to an architecture; AWS summarizes workflow types in What is Step Functions?.
Hand off work with API Gateway or a queue
| Handoff | How it works | When it fits |
|---|---|---|
| API Gateway | A Step Functions task invokes an API Gateway endpoint using arn:aws:states:::apigateway:invoke.waitForTaskToken. The token can be included in a request header, as in AWS’s example. |
Use when the external system can accept an API request to begin work and the request path should initiate the operation. |
| Amazon SQS | Step Functions publishes a message containing the task token. A consumer retrieves the message, performs the work and returns the token on completion. | Use when a queue’s buffering and decoupling are useful, or a worker should not depend on the workflow’s immediate request path. |
API Gateway request-response is the default integration behavior; the explicit .waitForTaskToken suffix is what makes Step Functions wait for the later callback. AWS’s API Gateway integration example demonstrates passing the token in a header. Its SQS callback example shows the queue-based handoff.
These are handoff shapes, not universal security recipes. In either design, configure the callback receiver so that only authenticated and authorized callers can submit completion, and ensure the identity used to call Step Functions has the required permissions.
Rank #3
Set task timeouts and heartbeats deliberately
Task states do not have a timeout by default in Amazon States Language, so AWS recommends defining a reasonable maximum duration rather than allowing a callback to wait indefinitely. Set TimeoutSeconds to bound the task. If a worker can report that it remains active, set HeartbeatSeconds to define the maximum permitted gap between heartbeats; when both are set, the heartbeat interval must be less than the task timeout.
TimeoutSeconds: the maximum duration for the task. A callback that does not arrive in time fails with a timeout.HeartbeatSeconds: the permitted interval without a heartbeat. A worker can callSendTaskHeartbeatwhile work remains active; exceeding the interval causes a timeout failure.- Overall limit: a heartbeat resets the heartbeat clock only. It does not extend the maximum duration set by
TimeoutSeconds.
Choose values from the expected work duration and recovery policy, not by copying an example value. A heartbeat reports liveness to Step Functions; it does not establish that the business operation is making useful progress. AWS explains the timeout and heartbeat fields in the Task state reference and heartbeat behavior in the SendTaskHeartbeat API reference. Heartbeat calls do not themselves add an event to execution history, though timeout events are recorded when a timeout occurs.
Plan for timeout recovery
Use the workflow’s error handling to decide what happens after a timeout or task failure: for example, notify an operator, trigger compensation, or make a deliberate retry decision. Retrying a callback task does not guarantee the external operation did not already finish, so coordinate retries with the worker and the business operation’s idempotency strategy.
Free tools Windows power users keep installed
One-click scans. No signup required.
Make retries and callbacks safe
Step Functions follows at-least-once execution semantics: a step may run more than once. The external handoff, business side effects, and callback processing therefore need to tolerate duplicate execution or have a way to detect it. AWS discusses this in its Step Functions best practices.
Best Value
- Keep a durable operation ID. Track the business operation independently of the task token. This lets your systems reconcile work across retries and timeouts.
- Protect the token. Treat it as a sensitive capability that can complete a task. Restrict access, avoid logging the raw token, and do not expose it in a public URL. Authenticate and authorize callback senders.
- Handle duplicate and late callbacks. A token for a task that has expired or closed will not complete that task. Define how the receiver records and responds to duplicate, malformed, or unknown callbacks without repeating business side effects.
- Record correlation safely. Log an application-level correlation ID and the callback outcome, not the raw token.
A timed-out callback task receives a newly generated random token. Do not assume an old token can complete a retry. AWS documents token behavior and callback restrictions in its integration pattern reference; the specific authentication and token-retention design is an implementation choice.
Quick Recap
Implementation checklist
- Choose a Standard Workflow and confirm that the selected service integration supports
.waitForTaskToken. - Select API Gateway for an API-initiated handoff or SQS when buffering and decoupling are useful.
- Pass the token only to the worker or receiver that needs it, and authorize the same-account principal that calls the Step Functions completion API.
- Set a realistic
TimeoutSeconds; addHeartbeatSecondsonly when the worker can report liveness. - Make work and callbacks duplicate-tolerant, and retain a separate durable operation ID for reconciliation.
- Specify how timeouts, failed work, late callbacks, and unknown tokens are handled.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
