Getting Started

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.

The Escalation Ladder
✓
submit_for_reviewManager notified with the report
⏸
gate: manager_approvalSuspended — up to 3 days
⏱
timeoutNo decision in 3 days — this is routing, not failure
✓
escalate_to_directorDirector notified
⏸
gate: director_approvalSuspended — up to 7 more days
=
decisionApproved → reimburse · rejected → notify employee
Ten days on the slowest path, zero resources the whole time — 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

1
import {
2
Workflow,
3
Tasks,
4
Task,
5
WorkflowContext,
6
createTaskRefs,
7
} from '@orcher/sdk';
8
9
@Tasks()
10
class ApprovalTasks {
11
@Task()
12
async submitForReview(report: ExpenseReport): Promise<void> {
13
await emailClient.notifyManager(report.managerId, report.id);
14
}
15
16
@Task()
17
async reimburseEmployee(input: ReimbursementInput): Promise<string> {
18
return await payrollClient.reimburse(input);
19
}
20
21
@Task()
22
async notifyRejection(input: RejectionNotice): Promise<void> {
23
await emailClient.sendRejection(input);
24
}
25
26
@Task()
27
async escalateToDirector(reportId: string): Promise<void> {
28
await emailClient.escalate(reportId);
29
}
30
}
31
32
const tasks = createTaskRefs(ApprovalTasks);
33
34
@Workflow({ name: 'expense_approval', version: '1.0.0' })
35
class ExpenseApproval {
36
async run(
37
ctx: WorkflowContext,
38
report: ExpenseReport,
39
): Promise<ApprovalResult> {
40
// Submit for manager review
41
await ctx.executeTask(tasks.submitForReview, report);
42
43
// Wait up to 3 days for manager approval
44
try {
45
const event = await ctx.waitForEventWithTimeout<ApprovalEvent>(
46
'manager_approval',
47
3 * 24 * 3600 * 1000, // 3 days in ms
48
);
49
50
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 director
65
await ctx.executeTask(tasks.escalateToDirector, report.id);
66
67
const escalated = await ctx.waitForEventWithTimeout<ApprovalEvent>(
68
'director_approval',
69
7 * 24 * 3600 * 1000, // 7 days in ms
70
);
71
72
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:

1
orcher 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:

Timeout as Failure vs. Timeout as Routing
Fail safe
Silence means no

When acting without an answer is dangerous — payments, compliance holds. A fraud review that expires auto-rejects; nothing moves.

Escalate
Silence means ask louder

When the request is legitimate and only attention is missing — approvals, reviews. This page's expense report climbs to the director.

Either way, decide explicitly — a chain must end in a terminal default.

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 on manager_approval without crossing wires. Your approval UI needs to store that execution ID when the review case is created — pass it in submit_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