Event Gates for Human Approvals
Many distributed workflows need to pause and wait for external input — a manager approving an expense, a webhook confirming a payment, or a compliance officer clearing a transaction. Event gates let the workflow suspend without consuming resources, preserving full state in PostgreSQL until the event arrives. You can attach timeouts that automatically escalate or reject when nobody responds.
How it works
The example chains two gates into an escalation ladder. The manager's timeout isn't a failure — it's a routing decision that notifies the director and opens a second, longer gate. On the slowest path the workflow lives for ten days; an approval at either gate exits early.
For the anatomy of a single gate — the event/timeout race and its three outcomes — see fraud detection's review gate. This page adds what happens when you chain them.
Example: expense approval with escalation
1import {2 Workflow,3 Tasks,4 Task,5 WorkflowContext,6 createTaskRefs,7} from '@orcher/sdk';89@Tasks()10class ApprovalTasks {11 @Task()12 async submitForReview(report: ExpenseReport): Promise<void> {13 await emailClient.notifyManager(report.managerId, report.id);14 }1516 @Task()17 async reimburseEmployee(input: ReimbursementInput): Promise<string> {18 return await payrollClient.reimburse(input);19 }2021 @Task()22 async notifyRejection(input: RejectionNotice): Promise<void> {23 await emailClient.sendRejection(input);24 }2526 @Task()27 async escalateToDirector(reportId: string): Promise<void> {28 await emailClient.escalate(reportId);29 }30}3132const tasks = createTaskRefs(ApprovalTasks);3334@Workflow({ name: 'expense_approval', version: '1.0.0' })35class ExpenseApproval {36 async run(37 ctx: WorkflowContext,38 report: ExpenseReport,39 ): Promise<ApprovalResult> {40 // Submit for manager review41 await ctx.executeTask(tasks.submitForReview, report);4243 // Wait up to 3 days for manager approval44 try {45 const event = await ctx.waitForEventWithTimeout<ApprovalEvent>(46 'manager_approval',47 3 * 24 * 3600 * 1000, // 3 days in ms48 );4950 if (event.approved) {51 const txnId = await ctx.executeTask(tasks.reimburseEmployee, {52 employeeId: report.employeeId,53 amount: report.amount,54 });55 return ApprovalResult.approved(txnId);56 } else {57 await ctx.executeTask(tasks.notifyRejection, {58 employeeId: report.employeeId,59 reason: event.comments ?? '',60 });61 return ApprovalResult.rejected(event.comments);62 }63 } catch {64 // Timeout — escalate to director65 await ctx.executeTask(tasks.escalateToDirector, report.id);6667 const escalated = await ctx.waitForEventWithTimeout<ApprovalEvent>(68 'director_approval',69 7 * 24 * 3600 * 1000, // 7 days in ms70 );7172 if (escalated.approved) {73 const txnId = await ctx.executeTask(tasks.reimburseEmployee, {74 employeeId: report.employeeId,75 amount: report.amount,76 });77 return ApprovalResult.approved(txnId);78 } else {79 return ApprovalResult.rejected(escalated.comments);80 }81 }82 }83}Send the approval event via the CLI or gRPC:
1orcher workflow event <execution-id> \2 --name manager_approval \3 --payload '{"approved": true, "approver": "alice@company.com"}'While the workflow is waiting, it consumes zero compute resources — no polling, no threads, no connections. The full workflow state lives in PostgreSQL. When the event arrives (via send_event gRPC call, CLI, or the Admin UI), Orcher wakes the workflow and resumes from exactly where it paused.
What should a timeout mean?
The same primitive supports opposite policies — the right one depends on what silence costs in your domain:
When acting without an answer is dangerous — payments, compliance holds. A fraud review that expires auto-rejects; nothing moves.
When the request is legitimate and only attention is missing — approvals, reviews. This page's expense report climbs to the director.
Design notes
- End the ladder deliberately. In this example the director's gate has no timeout handler — a second timeout fails the workflow. That's a valid terminal default (it surfaces as an error for ops), but choose it consciously; the alternative is a final auto-reject with a notification, as in fraud detection.
- Events are addressed to one execution. The CLI call targets
<execution-id>, so two pending expense reports can both wait onmanager_approvalwithout crossing wires. Your approval UI needs to store that execution ID when the review case is created — pass it insubmit_for_review. - The payload is part of the audit trail.
approver,comments, and the decision all arrive in the event and are journaled with it — who approved what, and when, comes free. Put the fields you'll want in six months into the payload now. - Deploys don't disturb the wait. The gate and its timeout live in the server, not the worker process — the same mechanics as durable timers. A three-day wait survives any number of releases.
Next Steps
- Child Workflows for Service Composition — Compose services into reusable workflow units.
- Saga Pattern with Automatic Rollback — Handle multi-service transaction failures with compensating actions.
- Multi-Service Deployment — Fan-out across regions with parallel execution.
- Best Practices & Performance — Guidelines and benchmarks for distributed workflows.