Step Wait (`:wait`)

Quick Answer

Use this reference for the :wait step schema, timeout semantics, and human/webhook resume patterns.

Use for webhook/event waits or human-in-the-loop pauses.

Canonical Shape

Core fields:

Field	Type	Required	Notes
`:key`	string/keyword	Yes	Correlation key
`:timeout`	string/number	No	Duration string (e.g. `"24h"`) or seconds
`:on-timeout`	keyword/string	No	`:fail` (default) or `:continue`
`:default-value`	any	No	Return value when timeout continues
`:notify`	map	No	Notification config (channel `:http`)
`:webhook`	map	No	Webhook auth/path config
`:event`	map	No	Event routing config (`:name`, optional key path)
`:roles`	vector	No	Role-based completion control
`:validation`	map	No	Required fields on completion payload

Limits And Behavior

Use a stable :key so external events can resume the flow.
Webhook waits are configured on triggers; waits pause execution.
:notify is optional and depends on your workspace notification setup.
For incoming webhooks, bind secret slots (:type :secret) via profile bindings to secure requests.
When :notify is present, the wait record includes approval URL templates you can render and share.
Email notifications use the same :http channel and an email API connection (for example SendGrid).
:on-timeout :continue should typically be paired with :default-value to keep downstream branches deterministic.

:notify fields (example shape):

:channels for per-channel configs (e.g. {:http {:connection :notify-api :path "/notify" :method :post}})
HTTP notifications require a connection slot; inline auth is not supported.

Canonical Examples

Minimal wait:

(flow/step :wait :webhook
           {:key "approval"
            :timeout "24h"
            :notify {:channels {:http {:connection :notify-api
                                       :path "/notify"
                                       :method :post}}}})

Email notification (SendGrid):

(flow/step :wait :approval
           {:key "approval-123"
            :timeout "24h"
            :notify {:channels
                     {:http {:connection :sendgrid
                             :path "/mail/send"
                             :method :post
                             :json {:personalizations [{:to [{:email "you@company.com"}]}]
                                    :from {:email "noreply@company.com" :name "Breyta"}
                                    :subject "Approval needed"
                                    :content [{:type "text/plain"
                                               :value "Approve: {{approvalUrl}}\nReject: {{rejectionUrl}}"}]}}}}})

Step-by-step: approval URL templates

Use this when a human must approve before the flow continues.

Add a wait step:

(flow/step :wait :approval
           {:key "approval-123"
            :timeout "10m"
            :notify {:channels {:http {:connection :notify-api
                                       :path "/notify"
                                       :method :post}}}})

Expected template output (from wait list):

{:approval
 {:template "{base-url}/{workspace-id}/waits/{wait-id}/{action}?token={token}"
  :params {:base-url "https://flows.breyta.ai"
           :workspace-id "ws_123"
           :wait-id "wait_abc"
           :token "token_..."}
  :actions [:approve :reject]}}

Start a run and list waits:

breyta flows run <slug> --input '{"n":41}'
breyta waits list --flow <slug>

Use the approval URL from the wait list output:

Open approvalUrl (or build from the template).
Approve or reject to resume the run.

Example wait list payload (approval URL template):

{:approval
 {:template "{base-url}/{workspace-id}/waits/{wait-id}/{action}?token={token}"
  :params {:workspace-id "ws_123"
           :wait-id "wait_abc"
           :token "token_..."}
  :actions [:approve :reject]}}

If you only need a single link, use approvalUrl or rejectionUrl from the wait list output.
These routes redirect to login when unauthenticated and then resume the action.

For notifications, approvalUrl and rejectionUrl are available as template data and should be referenced as {{approvalUrl}} and {{rejectionUrl}} in channel payload templates.