How Wait for Event Works
When you usecontext.waitForEvent()
in your workflow, Upstash Workflow automatically pauses execution and waits for an external notification to resume.
This happens without keeping your serverless function running, making it cost-effective and reliable for event-driven workflows.
Each waiter has a timeout duration to wait for the event and then fires automatically.
Wait for Event timeouts have limits based on your pricing plan:
- Free: Maximum timeout of 7 days
- Pay-as-you-go: Maximum timeout of 1 year
- Fixed pricing: Custom timeouts (no limit)
Race Condition Between Wait and Notify
A race condition can occur whennotify
is called before waitForEvent
is executed.
In this scenario, the notification will be sent but no workflow will be waiting to receive it, causing the event to be lost.
To prevent race conditions, always check the response of the notify
operation.
The notify
method returns a list of notified waiters.
If this list is empty, it means no workflows were waiting for the event, and you should retry the notification.
Selecting an Event ID
When a workflow run waits on an event ID, it’s appended to a list of waiters for the event ID. When a notify request is sent, all workflow runs waiting for that event are notified sequentially. To avoid heavy notify operations, it’s recommended to use unique event IDs instead of generic ones. For example, instead of waiting onuser-sent-verification
, wait the workflow on user-{userId}-sent-verification
event.