In a hosted workflow engine, how does a step wait days for a human approval without a function running, and what ends the wait?
answer
- state lives in the engine
- nothing executes while paused
- a token handed to the outside
- the resume call carries the token
- a timeout on the wait itself
basics
~20 sThe step issues a callback token, the engine saves the execution and runs nothing, and the reviewer's system resumes it by calling the engine with that token. A timeout on the wait ends executions whose token never returns.
solid answer
~50 sA function cannot be the thing that waits: function platforms typically enforce a per-invocation time limit measured in minutes, and sleeping inside one bills compute for doing nothing. In a hosted workflow engine the approval step instead **issues a callback token** and sends it out with the review request (an email link, a queue message, a row in a task list). The engine **persists the execution and pauses it**; no function is running. When the reviewer decides, their system calls the engine's resume API with the token and a success or failure payload, and the execution continues from that step. Because a token can be lost, the wait gets its own **timeout** (and, for long external jobs, a heartbeat), so the step fails into an escalation path instead of hanging forever. On engines priced per step, the paused days cost very little.
code
json · 16 lines{
"ReviewDocument": {
"type": "waitForCallback",
"send": {
"queue": "review-requests",
"message": {
"documentId": "{{input.documentId}}",
"callbackToken": "{{engine.token}}"
}
},
"timeout": "P3D",
"onSuccess": "Publish",
"onFailure": "Reject",
"onTimeout": "EscalateReview"
}
}go deeper
Recall that a paused execution lives in the engine's storage, not in a running function, and that a token plus a resume call is what wakes it up.
Explain the whole loop: token issued, sent out with the work, execution persisted, resume API called with success or failure, and the timeout path when nothing comes back.
Show the failure modes you guard in production: lost tokens caught by timeouts, leaked tokens, duplicate completions treated as success, and result payloads validated on entry.
Weigh where long human waits belong: inside the hosted engine's execution, or in a separate task system that starts a fresh execution once the decision lands.
## Why a function cannot be the thing that waits Take a document pipeline: a user uploads a contract, a function extracts its text, a person reviews it, and an approved document is published. The review can take an hour or three days. Two facts about functions rule out waiting inside one: - Function platforms typically enforce a **per-invocation time limit measured in minutes**, not days. A handler that sleeps until a reviewer clicks is killed long before the click, and the plans that allow longer runs still bill for every idle hour. - Even inside the limit, a sleeping handler is **billed for wall-clock duration** while doing nothing, and it holds a slot of the function's concurrency that real traffic could use. Polling does not fix this. A scheduled function that wakes up to check "is it approved yet?" still has to remember which documents it is waiting on, and that state has to live somewhere durable. A **hosted workflow engine** is that somewhere. ## How a callback wait works A hosted workflow engine runs an **execution** (one run of the workflow for one document) as a series of steps and stores the execution's state between them. A **callback wait** is a step that pauses the execution until an outside system reports back. The sequence is: 1. The execution reaches the review step. The engine generates a **callback token**, an opaque value that identifies this exact waiting step. 2. The step sends the token outward together with the work: a message on a review queue, a row in a task table, or a link in an email to the reviewer. 3. The engine **persists the execution** (its input, the results so far, and the fact that it is waiting on this token) and stops. No function is running and no instance is held. 4. The reviewer approves or rejects in their own tool. That tool calls the engine's resume API with the token and either a **success payload** (for example `{"approved": true}`) or a **failure** with an error name. 5. The engine loads the saved execution, records the result, and moves to the next step: publish on success, a rejection branch on failure. The engine, not your code, is the memory of what is waiting on whom. That is why the wait can last days and survive deploys and restarts of everything around it. ## What ends the wait A callback wait has three ways to end, and an operator should design all three: | Ending | What triggers it | Where the execution goes | |---|---|---| | Success | The resume API is called with the token and a result | The next step, with the result as input | | Failure | The resume API is called with the token and an error | The step's error handling, such as a rejection branch | | Timeout | No completion arrives before the step's timeout | A timeout error the definition routes to escalation or a reminder | Without a timeout, a lost email or a crashed review tool leaves the execution waiting until the engine's own maximum execution duration, if it has one, which may be far longer than anyone wants. A sensible timeout routes to an **escalation path**: remind the reviewer, reassign, or close the document as unreviewed. For waits on a long-running external job rather than a person, many engines also accept **heartbeats**: the job reports in periodically with the token, and if the reports stop, the step fails early instead of waiting out the whole timeout. ## What goes wrong in production - **Lost tokens.** The message carrying the token is dropped or the reviewer tool loses it. Only the timeout rescues the execution. - **Leaked tokens.** Anyone holding the token can complete the step. Treat it like a credential: send it only to the system that needs it and avoid logging it in full. - **Duplicate completions.** A reviewer double-clicks, or the review tool retries its call. Engines typically accept one completion per token and reject the rest, so the tool should treat "already completed" as success, not as an error to retry forever. - **Payload shape drift.** The next step expects a field the review tool stopped sending. Validate the result where it enters the workflow. ## What the wait costs On engines that price **per step or state transition**, a paused execution costs little while it waits; the bill comes from the steps it runs, not from the days in between. Engine types billed by **execution duration** are a different matter and suit short flows rather than human waits. Either way, nothing is paying for a function to sit idle, which is the point of moving the wait out of the function.
- Why should a workflow's callback token be handled like a credential?Whoever holds the token can complete or fail that waiting step, so a leaked token lets someone approve a document they never reviewed. Send it only to the system that needs it, keep it out of full-text logs, and have the review tool authenticate its users before it calls the resume API. The engine verifies the token and the calling system's credentials, not which person approved.
- What does a heartbeat add on top of a timeout for a callback wait?The timeout bounds the whole wait; a heartbeat bounds silence. A long external job reports in with its token at intervals, and if those reports stop, the engine fails the step soon after the job dies instead of at the end of the full timeout. It suits waits on machines; a human reviewer usually gets a plain timeout with reminders.
A busy restaurant hands you a buzzer instead of making you stand at the counter: you sit down, the kitchen keeps your order on a ticket, and the buzzer calls you back when the food is ready. A good restaurant also has a rule for the buzzer that never goes off: after a while, someone comes to find you.
- A function can simply poll the database in a loop until the reviewer approves.
- The paused execution keeps a function instance alive until the callback arrives.
- No timeout is needed on an approval step because reviewers always answer eventually.
- The callback token is just an ID, so it is safe to log and share widely.
- If the review tool gets an already-completed error, it should keep retrying the call.