Skip to main content
Live. This area is documented as current, user-reliable behavior.

​
Goal

Use event waiting and correlation keys for user actions, payments, webhooks, and external approvals.

​
Prerequisites

  • A workflow that needs to wait for something outside the process

​
Workflow

1
Wait for an event by name.
2
Use a correlation key that identifies the specific user, order, invoice, or resource.
3
Send the external event with the same event name and correlation key.
4
Decide 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. 
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. 
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.

Durable Jobs workflows

Use steps and events to build multi-step jobs that can retry, pause, and resume.

Idempotency

Use idempotency keys so duplicate requests do not create duplicate work.