Velt Approval Engine Best Practices

Implementation guide for the Velt Approval Engine — a declarative workflow runtime for multi-step agent + human approval processes. Covers the workflow model (definitions = nodes + edges + groups), the 14 REST endpoints under /v2/workflow/* (definitions, executions, steps), webhook delivery with HMAC signature verification, and idempotency/recovery patterns.

When to Apply

Reference these guidelines when:

• Authoring approval workflow definitions — nodes (agent, human), edges (with optional when gating expressions), groups (parallel quorum)
• Dispatching executions — always with an idempotencyKey; configuring webhookUrl + webhookSecret together
• Recording decisions — human reviewer approvals/rejections (/steps/recordReviewerDecision) or external blocking-agent resolutions (/steps/recordAgentResolution)
• Building webhook receivers — HMAC-SHA256 signature verification on raw bytes, idempotency on (executionId, seq), retry schedule, missed-event recovery
• Using quorum groups with waitAll / cancelOnQuorum / joinOnQuorum policies
• Configuring SLAs (slaMs on a node) and the required breach-routed outgoing edge
• Admin-scoped operations (/steps/cancel, /steps/resolve)
• Debugging INVALID_ARGUMENT linter rejections (cycle, dangling-edge, unreachable-node, missing-breach-edge, group-joinonquorum-members-must-share-successors)

For general Velt REST API patterns (Comments, Notifications, Activity, etc.), see velt-rest-apis-best-practices — only the Approval Engine domain is covered here.

Rule Categories by Priority