Durable Jobs
Event Waiting + Correlation
LivePause a workflow until the right external event arrives, then resume the correct run.
Goal
Use event waiting and correlation keys for user actions, payments, webhooks, and external approvals.
Current status
Live
This area is documented as current, user-reliable behavior.
Workflow
- 1Wait for an event by name.
- 2Use a correlation key that identifies the specific user, order, invoice, or resource.
- 3Send the external event with the same event name and correlation key.
- 4Decide what should happen if the event never arrives.
Wait for an event
Backend flows often need to pause for something external: an email click, payment confirmation, manual approval, or webhook from another system.
Pause the workflow
await step.waitForEvent('email.verified', {
correlationKey: `user:${userId}`,
timeout: '24h',
onTimeout: 'fail',
})What happens while waiting
- The workflow pauses.
- State and completed steps are saved.
- No compute runs while the workflow is waiting.
- The workflow resumes when a matching event arrives.
Correlation
Multiple workflows may wait for the same event name. Correlation tells StackShift which waiting run should resume.
Matching uses the event name plus correlationKey.
Send the matching event
await stackshift.events.send(
'email.verified',
{ userId: '123' },
{
correlationKey: 'user:123',
idempotencyKey: 'email.verified:user:123',
}
)Timeout behavior
- fail: mark the run failed when the timeout expires.
- continue: resume the workflow with a timeout result so your code can choose the next step.
- cancel: cancel the run when waiting is no longer useful.
Durable events
- Events are stored durably.
- An event can arrive before or after the workflow reaches the wait.
- StackShift matches stored events and waiting runs by event name and correlation key.
Expected result
The right workflow resumes even when many workflows are waiting for the same event name.