step.waitForEvent()

Overview

step.waitForEvent() pauses a workflow until an external event is delivered. This is perfect for human-in-the-loop workflows, webhooks, or any scenario where your workflow needs to wait for something to happen in the outside world.

The event name must match a key from the workflow's events schema, and the returned payload is fully typed.

Basic Usage

const workflow = defineWorkflow((t) => ({
	type: 'approval-flow',
	input: t.object({ requestId: t.string() }),
	events: {
		approval: t.object({
			approved: t.boolean(),
			reviewer: t.string(),
		}),
	},
	run: async (step, payload) => {
		await step.do('submit-request', async () => {
			await submitForReview(payload.requestId);
		});

		// Wait up to 48 hours for approval
		const decision = await step.waitForEvent('approval', {
			timeout: '48h',
		});

		if (decision.approved) {
			await step.do('process-approval', async () => {
				await processApproval(payload.requestId, decision.reviewer);
			});
		}

		return { approved: decision.approved, reviewer: decision.reviewer };
	},
}));

Timeouts

Without a timeout, workflows wait indefinitely for events. This is often exactly what you want for human-in-the-loop workflows.

// Wait forever for user approval
const approval = await step.waitForEvent('user-approval');

With a timeout, the workflow is marked as errored with EventTimeoutError if the event doesn't arrive in time:

await step.waitForEvent('webhook', { timeout: '5m' }); // 5 minutes
await step.waitForEvent('approval', { timeout: '48h' }); // 2 days
await step.waitForEvent('payment', { timeout: '30s' }); // 30 seconds

Timeouts use duration strings like "30s", "5m", "1h", or "7d".

How It Works

Here's what happens when you call step.waitForEvent():

First Execution

1. Creates a "waiting" step in SQLite with the event name and optional timeoutAt timestamp
2. Throws a WaitInterrupt (not an Error — this is normal flow control)
3. The workflow runner catches the interrupt
4. If there's a timeout, the Durable Object sets an alarm for the timeout time
5. The Durable Object hibernates

When a Buffered Event Exists

If the event was already sent before the workflow reached this step:

1. step.waitForEvent() checks the event buffer
2. If a matching buffered event is found, it is consumed immediately
3. The step is persisted as "completed" with the buffered payload
4. Execution continues without suspending — no WaitInterrupt, no alarm
5. On subsequent replays, the step returns the cached result as usual

When an Event Arrives

1. External code calls ablauf.sendEvent()
2. The event payload is validated against the schema
3. The Durable Object wakes up
4. The waiting step is marked as "completed" with the event payload stored in SQLite
5. The workflow replays from the beginning
6. All previous steps return cached results instantly
7. step.waitForEvent() sees the step is completed and returns the event payload
8. Execution continues

If the Timeout Fires

1. The Durable Object wakes up from the alarm
2. The step is marked as "failed" with EventTimeoutError
3. The workflow replays
4. step.waitForEvent() sees the step failed and re-throws the error
5. The workflow is marked as errored

Subsequent Replays

On any future replay (even if the workflow crashes and restarts), the completed event step returns the cached event payload instantly. The workflow doesn't wait again.

Type Safety

The return type of step.waitForEvent() is automatically inferred from your event schemas:

events: {
	payment: t.object({
		amount: t.number(),
		currency: t.string(),
	}),
}

// Inside run():
const payment = await step.waitForEvent("payment");
// TypeScript knows: payment is { amount: number, currency: string }

payment.amount; // ✅ number
payment.currency; // ✅ string
payment.unknownField; // ❌ TypeScript error

The event name is also type-checked:

await step.waitForEvent('payment'); // ✅ "payment" is in the events schema
await step.waitForEvent('unknown'); // ❌ TypeScript error

This makes it impossible to wait for an event that doesn't exist or to access fields that aren't in the schema.

Step Name Uniqueness

Like all step primitives, event wait step names must be unique:

// ❌ This will throw DuplicateStepError
await step.waitForEvent('approval');
await step.waitForEvent('approval');

// ✅ This is fine if you need to wait for the same event type multiple times
await step.waitForEvent('first-approval');
await step.waitForEvent('second-approval');