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, hands a task token to the external process, and resumes only after an authorized caller returns that token with SendTaskSuccess or SendTaskFailure. Set a maximum wait, and use heartbeats when the worker can report that it is still active.
How the callback pattern works
A callback task separates starting work from completing it. Step Functions creates a task token, passes it to a service or worker, and waits. The external process performs the work independently, then calls the Step Functions API with the token and either a success result or failure details. The callback must come from a principal in the same AWS account as the state machine. See AWS’s service integration patterns.
As an Amazon Associate I earn from qualifying purchases.
- Start: A Task state invokes an integration configured with
.waitForTaskToken. - Handoff: The integration sends the task token and any required business data to a callback receiver or queue.
- Work: An external service or worker performs the operation without keeping the original request open.
- Complete: The worker calls
SendTaskSuccessorSendTaskFailurewith the token. - Resume: Step Functions completes or fails the Task state and continues according to the workflow definition.
In an AWS SDK integration, the selected API action must have a parameter that can carry the token. Step Functions exposes the token through its Context object. A callback task that times out receives a newly generated random token, so a previous token cannot be treated as a permanent identifier.
Free tools Windows power users keep installed
One-click scans. No signup required.
Choose the right integration pattern
Step Functions offers three broad approaches: request-response, job-run integrations that wait for a supported service job, and callback tasks that wait for an external party to return a token. Use request-response when the service response means the work is complete. Use a supported job integration when Step Functions can track that service’s job. Use a callback when an external system owns completion or the work cannot sensibly remain tied to a synchronous request. Supported patterns vary by service; check AWS’s integration-pattern documentation for the service you plan to call.
#1 Best Overall
| Approach | How completion is detected | Useful when | Important constraint |
|---|---|---|---|
| Request-response | The integrated service returns its response. | The operation finishes within the request’s practical time window. | An HTTP Task has a maximum timeout of 60 seconds, even if a higher value is requested. AWS documents this in Task workflow state. |
Run a job (.sync) |
Step Functions waits for a supported integrated job to finish. | The service has a supported job integration and owns job status. | Availability depends on the specific service integration. |
Callback (.waitForTaskToken) |
An external caller returns the task token with a success or failure result. | Another system or worker controls when the operation is complete. | Callback-token integrations require a Standard Workflow; Express Workflows support request-response integrations only. Confirm the relevant support details in AWS’s Step Functions overview. |
A callback task can wait up to the one-year Step Functions service quota, subject to its configured timeout and heartbeat behavior. That limit is not a reason to leave a task unbounded: set a duration that matches the operation and your recovery policy. The HTTP Task limit and service quota are described in AWS’s Task state documentation.
Hand off the token with API Gateway or a queue
API Gateway for a webhook-style handoff
For an API Gateway integration, the callback resource is arn:aws:states:::apigateway:invoke.waitForTaskToken. AWS’s example passes the token in a request header such as TaskToken; the receiving system retains it for the completion call. The .waitForTaskToken suffix is essential: request-response is the default and does not make the workflow wait for a later callback. Follow the configuration pattern in AWS’s API Gateway integration example.
Rank #2
- Upgraded Two Zipper Pockets: Forvencer server books feature two secure zipper pockets for better organization of coins, cash, and receipts, ensuring that everything you collect has a safe and secure place
- Smart Storage & Quick Access: Designed with 8 multi-functional compartments, the right side includes a guest receipt pad, while the left has a money pocket, ticket pocket, and credit card slot. Two small clear pockets store bills, receipts, and other visible items. A stitched pen loop ensures you always have your favorite pen ready
- High-quality & Easy to Clean: Crafted from high-quality PU leather with heavy-duty stitching, this server book is built to last. It resists tears, scratches, and its waterproof surface makes cleaning easy with just a damp cloth or a non-chlorine sanitizer
- Perfect Fit for Your Apron: Measuring 5” x 8”, this compact organizer is slightly smaller than other models, making it ideal for bending or sitting while carrying in your server apron. It holds everything a waitress needs—a place for everything
- What's Included: This server organizer comes with multiple open and zippered pockets to store money, receipts, tips, etc. Clear sleeves are perfect for keeping menus or special lists while serving. Available in a variety of colors, allowing you to express yourself even when in uniform
At a high level, the state definition supplies the token from the Context object in the API Gateway request, alongside the data the external service needs. The API request starts or registers the work; it should not be mistaken for the final completion signal. The external callback receiver must authenticate and authorize the sender, then call the Step Functions completion API using an authorized same-account principal.
SQS for a decoupled handoff
If the worker should not depend on an immediate webhook request path, Step Functions can publish a message containing the token to SQS. A consumer retrieves the message, performs the work, and returns the token when done. A queue can buffer work while consumers are busy and separate workflow initiation from worker availability. AWS provides an example using SQS, SNS, and Lambda in its callback task sample.
Choose between these handoffs based on the receiving system: API Gateway is a direct API-oriented handoff; a queue is useful when buffering and worker decoupling matter. Neither removes the need to protect the token or handle duplicate and late messages.
Bound the wait and monitor liveness
Task timeouts are not specified by default in Amazon States Language, so AWS recommends setting a reasonable TimeoutSeconds rather than allowing a task to wait indefinitely. This is the maximum task duration. If a worker can report that it remains active, set HeartbeatSeconds as well; when both are set, the heartbeat interval must be less than the overall timeout. Exceeding the heartbeat interval fails the task with a timeout error. See AWS’s guidance on timeouts and best practices and the Task state fields.
- Set
TimeoutSecondsto the longest reasonable duration for the operation, considering how and when you can recover or retry it. - Set
HeartbeatSecondsonly if the worker can sendSendTaskHeartbeatperiodically while the work remains active. - Catch timeout and task failures where the workflow needs to notify someone, compensate for partial work, or make a deliberate retry decision.
- Do not treat a heartbeat as evidence of useful business progress. It reports liveness to Step Functions, not whether the operation is advancing correctly.
A heartbeat resets the heartbeat clock; it does not extend the maximum duration set by TimeoutSeconds. AWS also notes that heartbeat calls do not themselves add an event to execution history, while timeout events are recorded when a timeout occurs. Details are in the SendTaskHeartbeat API reference.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Clear out junk files and repair common Windows errors3Scan for outdated or missing drivers - takes under a minuteDesign for retries, duplicate work, and late callbacks
Step Functions uses at-least-once execution semantics: a workflow step may run more than once. Downstream side effects should therefore be idempotent or otherwise tolerant of duplicates. Use a durable business-operation ID for reconciliation, separate from the task token, because a timed-out callback task gets a new token. AWS discusses this behavior in its best-practices guide and integration-pattern documentation.
Best Value
- Protect the token: Treat it as a sensitive capability that can complete a task. Restrict access, avoid putting it in public URLs or routine logs, and authenticate and authorize callback senders. AWS documents token delivery and account restrictions, but does not mandate one universal webhook-authentication design.
- Track without exposing secrets: Record an application-level correlation ID and callback outcome, not the raw token.
- Handle callback errors: Reject or safely record malformed, unknown, duplicate, and late callbacks. A token for a timed-out or closed task will not complete it; AWS documents invalid-token and timed-out-task errors in its heartbeat API reference.
- Reconcile business state: If work succeeds after the waiting task has timed out, use the business-operation ID to determine whether to compensate, retry, or record the result outside that expired callback.
These safeguards are implementation choices rather than a single AWS-prescribed receiver architecture. The token’s role in completing a task makes access control, correlation, and duplicate handling essential parts of the design.
When an Activity worker is a better fit
If you want a worker to poll for tasks rather than receive work through an API or queue integration, Step Functions Activities provide a worker-based pattern. The worker polls for work, performs it, and reports completion. This is a different handoff model from passing a callback token through an API Gateway request, and it requires deploying and operating the worker. AWS describes the model in Learn about Activities in Step Functions.
Quick Recap
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.
